Preparing PostgreSQL for Django on Fly.io

This article details the necessary steps within your Django project and using the flyctl CLI to correctly provision, connect, and configure a production-ready PostgreSQL database cluster on the Fly.io platform.

The recommended approach uses the flyctl CLI to create and link a dedicated PostgreSQL cluster (which runs as a separate Fly.io app) and uses the DATABASE_URL environment variable to configure Django.

1. Project Preparation (In your Django App)

Install PostgreSQL Adapter & Config Tool:

Install the necessary packages to allow Django to connect to PostgreSQL using a URL.

Command: pip install psycopg[binary] dj-database-url

Update settings.py:

Use dj-database-url to parse the connection string from the environment variable. This configuration allows your local setup to use SQLite while production uses PostgreSQL.

import os
import dj_database_url

# ... other settings

# DATABASES config
if os.environ.get('DATABASE_URL'):
    # In production, use the DATABASE_URL set by Fly.io
    DATABASES = {
        'default': dj_database_url.config(
            conn_max_age=600,
            conn_health_checks=True,
            ssl_require=True, # Important for production security
        )
    }
else:
    # In local development, use SQLite
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.sqlite3',
            'NAME': BASE_DIR / 'db.sqlite3',
        }
    }
  

2. Fly.io Database Provisioning

Create the PostgreSQL Cluster:

Use the fly postgres create command. This launches a dedicated PostgreSQL app within your Fly.io organization. You'll be prompted to choose a name, region, and VM size.

Command: fly postgres create

Attach to Your Django App:

Use the fly postgres attach command to securely link the two apps.

Command: fly postgres attach <postgres-app-name> -a <your-django-app-name>

Result: This command automatically creates a dedicated database and user, and then sets the DATABASE_URL as a secret on your Django app, completing the connection setup.

3. Final Deployment & Migration

These steps are repeated from the main deployment guide but are crucial for the database setup.

Deploy:

Run your standard deployment command to push the configured Django code to Fly.io.

Command: fly deploy

Run Migrations:

Execute the database migrations on the live production machine to create your tables in the PostgreSQL database.

Command: fly ssh console --pty -C "python manage.py migrate"