django-phased-migrations

Minimal external library to support phased migrations for rolling deploys with two (or more) Django backends sharing one Postgres database.

The library does not override Django’s built-in migrate command. Instead, it ships its own management commands that use Django’s public migration APIs.

Installation

pip install django-phased-migrations

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_phased_migrations",
]

Migration classification rule

• Contract migrations: migration module name ends with _contract (i.e. filename ends with *_contract.py)
• Expand migrations: everything else (including all historical migrations without suffix)

Example:

• myapp/migrations/0012_drop_old_column_contract.py → contract
• myapp/migrations/0011_add_new_column.py → expand

Commands

• manage.py migrate_expand

  • Applies only expand migrations.
  • Never applies contract migrations.
  • Warns if contract migrations are pending.
  • Fails fast if reaching an expand target would require applying a contract migration.

• manage.py migrate_contract

  • Applies only contract migrations.
  • Fails fast if it would need to apply any non-contract migration (run migrate_expand first).

• manage.py phased_migration_status

  • Shows what expand/contract migrations are pending (unapplied).

Recommended ops workflow (expand / deploy / contract)

• Expand

python manage.py migrate_expand

• Deploy

  • Roll deploy your new application code (both backends can run safely against the expanded schema).

• Contract

python manage.py migrate_contract

Failure modes and guardrails

• If an expand migration depends on a contract migration:

  • migrate_expand will error explaining that a contract migration would be required.

• If migrate_contract would need to apply expand migrations (e.g. you forgot to run expand first):

  • migrate_contract will error telling you to run migrate_expand first.

Notes / constraints (v1)

• Operates on the default database connection (optionally takes --database for parity with Django).
• No backfill manifest/state table; use normal Django operations (RunSQL, RunPython) or manual steps.