django-pg-zero-downtime-migrations

What it is and what it does

django-pg-zero-downtime-migrations is a custom Django database backend for PostgreSQL that replaces the standard backend to apply schema migrations while respecting database-level locks. Instead of using transactions for all migrations (which can cause table locks and downtime), it applies schema changes and SQL operations in a way that minimizes lock contention and allows the application to remain available during deployment.

The package works by managing PostgreSQL's table-level locks—ACCESS EXCLUSIVE, SHARE UPDATE EXCLUSIVE, and others—and applying configurable timeouts to prevent long-running operations from blocking application queries. It requires careful deployment orchestration: migrations are applied first, then application instances are restarted one at a time behind a load balancer to ensure the old and new application versions both work with the new schema. The package is in beta and does not apply zero-downtime guarantees to RunPython operations, only to schema and RunSQL migrations.

Use it for

• Deploying schema changes to a live PostgreSQL database serving multiple application instances without taking the application offline.
• Adding or modifying columns and indexes on large tables where standard Django migrations would cause extended lock times.
• Recovering from partial migration failures by re-running failed migrations in idempotent mode after fixing underlying data issues.
• Enforcing safe migration practices by raising errors on potentially unsafe operations when ZERO_DOWNTIME_MIGRATIONS_RAISE_FOR_UNSAFE is enabled.
• Managing long-running operations like index creation or constraint validation without triggering global statement timeouts.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

django-pg-zero-downtime-migrations on PyPI

Before you install

Low friction installation with a single dependency on django. The package is marked beta and aging (434 days since release), but the repository remains active with recent commits and moderate community adoption (573 stars). Suitable for production use with careful testing of migrations before deployment.

Requires PostgreSQL database; does not apply zero-downtime guarantees to RunPython operations, only schema and RunSQL migrations. Migrations are not wrapped in transactions, so partial failures require manual database state recovery.

License in practice

MIT license is permissive and imposes no restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

pip install django-pg-zero-downtime-migrations

In settings.py:
DATABASES = {
    'default': {
        'ENGINE': 'django_zero_downtime_migrations.backends.postgres',
        ...
    }
}
ZERO_DOWNTIME_MIGRATIONS_LOCK_TIMEOUT = '2s'
ZERO_DOWNTIME_MIGRATIONS_STATEMENT_TIMEOUT = '2s'
ZERO_DOWNTIME_MIGRATIONS_RAISE_FOR_UNSAFE = True

Package facts

Evidence: django_pg_zero_downtime_migrations-0.19-py3-none-any.whl

Tags

More Database packages

See also django-pg-migration-tools · django-pgmigrate · django-postgres-extra · migra · squawk-cli · django-syzygy · django-pglocks · django-pglock · django-safemigrate · yoyo-migrations