SUPABASE_SETUP.md

Supabase Setup Guide for Hugging Face Deployment

Why Supabase?

• Persistent Database: Data survives container restarts
• Production Ready: Scalable PostgreSQL database
• Free Tier: Generous free tier for development
• Easy Setup: Managed PostgreSQL with automatic backups
• Real-time: Built-in real-time subscriptions (if needed)

Step 1: Create Supabase Project

1. Go to https://supabase.com
2. Sign up/Login with GitHub
3. Click "New Project"
4. Choose organization and project name
5. Set a strong database password
6. Choose a region close to your users
7. Wait for setup to complete (2-3 minutes)

Step 2: Get Database Connection Details

1. In your Supabase dashboard, go to Settings → Database
2. Find the Connection string section
3. Copy the URI (it looks like: postgresql://postgres:[password]@[host]:5432/postgres)

Step 3: Configure Hugging Face Spaces

Option A: Using Hugging Face Spaces Environment Variables

1. Go to your Hugging Face Space
2. Click Settings → Repository secrets
3. Add these secrets:

SUPABASE_DB_URL=postgresql+asyncpg://postgres:[password]@[host]:5432/postgres
ENVIRONMENT=production

Option B: Using .env file (for local testing)

Create a .env file in your project root:

# Supabase Database
SUPABASE_DB_URL=postgresql+asyncpg://postgres:[password]@[host]:5432/postgres
ENVIRONMENT=production

# Other settings
OPENAI_API_KEY=your_openai_key_here
SECRET_KEY=your_secret_key_here

Step 4: Database Schema Setup

The application will automatically create all tables on startup. However, if you want to use Alembic for migrations:

1. Install Alembic: pip install alembic
2. Initialize: alembic init alembic
3. Create migration: alembic revision --autogenerate -m "Initial migration"
4. Apply: alembic upgrade head

Step 5: Test the Connection

The application will automatically:

• Connect to Supabase on startup
• Create all necessary tables
• Log the connection status

Environment Variables Reference

Variable	Description	Required
SUPABASE_DB_URL	PostgreSQL connection string	Yes (for production)
ENVIRONMENT	Set to "production" for Supabase	Yes
DATABASE_URL	Fallback SQLite URL	No (for development)

Troubleshooting

Connection Issues

• Verify the connection string format
• Check if the database password is correct
• Ensure the host is accessible from Hugging Face

Permission Issues

• Supabase automatically creates the postgres user with full permissions
• No additional setup needed for basic operations

Performance Issues

• The connection pool is optimized for Hugging Face Spaces
• Pool size reduced to 5 connections to avoid limits

Security Notes

• Never commit database credentials to version control
• Use Hugging Face secrets for production
• Supabase automatically handles SSL connections
• Database is automatically backed up

Migration from SQLite

The application automatically detects the environment and switches to Supabase when:

• ENVIRONMENT=production is set
• SUPABASE_DB_URL is provided

No code changes needed - it's handled automatically by the configuration system.