quantum-ai-v3/RAILWAY_DATABASE_SETUP.md

🗄️ Railway PostgreSQL Database Setup

Current Status

✅ Django settings.py is already configured to use Railway PostgreSQL
✅ Django app is starting successfully
❌ Need to set DATABASE_URL environment variable

Step-by-Step Railway Database Configuration

Step 1: Ensure PostgreSQL Service is Added

1. Go to your Railway project dashboard
2. Click "Add Service" → "Database" → "PostgreSQL"
3. Wait for PostgreSQL service to deploy (shows green/active status)

Step 2: Set DATABASE_URL Environment Variable

1. Go to your Railway project → Variables tab
2. Click "Add Variable"
3. Set:
   • Name: DATABASE_URL
   • Value: ${{ Postgres.DATABASE_URL }}

Step 3: Verify Variable Resolution

Railway will automatically resolve ${{ Postgres.DATABASE_URL }} to the actual PostgreSQL connection string:

postgresql://postgres:password@hostname:5432/railway

Step 4: Deploy Changes

Since you're updating environment variables, Railway will automatically redeploy your app.

How Django Will Use This

Your Current Settings (Already Perfect)

# In settings.py - already configured correctly
database_url = config('DATABASE_URL', default='')

if database_url:
    # Parse Railway PostgreSQL URL
    DATABASES = {
        'default': dj_database_url.parse(database_url, conn_max_age=600)
    }
else:
    # Fallback to SQLite for local development
    DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', ...}}

What Happens After Setup

1. Railway resolves variable: ${{ Postgres.DATABASE_URL }} → actual connection string
2. Django reads DATABASE_URL: From environment variables
3. dj_database_url parses: Converts URL to Django database config
4. Connection pooling: conn_max_age=600 keeps connections alive

Testing Database Connection

After Railway Deployment

# Test database connection
railway run python manage.py check_db

# Run migrations and setup
railway run python manage.py setup_database

# Or manually:
railway run python manage.py migrate
railway run python manage.py populate_agents

Expected Success Output

Database connection successful!
Running database migrations...
Migrations completed successfully!
Populating agents...
Agents populated successfully!
Database setup completed!

Troubleshooting

Issue: Database Connection Failed

Cause: PostgreSQL service not running or DATABASE_URL not set Fix: Ensure PostgreSQL service is active and DATABASE_URL variable is set

Issue: No Such Table Errors

Cause: Migrations haven't been run Fix: Run railway run python manage.py setup_database

Issue: Permission Denied

Cause: Database user permissions Fix: Railway PostgreSQL should have full permissions by default

Verification Steps

1. Check Railway Dashboard

• ✅ PostgreSQL service shows "Active"
• ✅ DATABASE_URL variable exists
• ✅ App deployment successful

2. Test Health Endpoint

curl https://your-railway-domain.railway.app/health/

Expected response:

{
  "status": "healthy",
  "checks": {
    "database": {"status": "healthy"},
    "agents": {"status": "healthy", "active_count": 6}
  }
}

3. Test Application Access

• Visit Railway domain in browser
• Should show homepage without database errors
• All 6 AI agents should be accessible

Summary

Your Django code is already perfectly configured for Railway PostgreSQL. You just need to:

1. Add PostgreSQL service (if not already added)
2. Set DATABASE_URL = ${{ Postgres.DATABASE_URL }} in Railway variables
3. Run database setup after deployment

That's it! 🚀