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

Provides a Django database backend for PostgreSQL that executes migrations while minimizing table locks, enabling schema changes without application downtime.

Yes, with conditions. Install this if you need zero-downtime schema migrations on PostgreSQL and can follow the deployment flow (apply migrations, then restart instances one at a time). The package is mature enough for production use (MIT licensed, actively maintained, 573 stars) but remains in beta—test all migrations thoroughly before production deployment. Not suitable if your migrations rely heavily on RunPython operations or if you cannot orchestrate instance restarts behind a load balancer.

Install

django-pg-zero-downtime-migrations on PyPI

pip install django-pg-zero-downtime-migrations

uv add django-pg-zero-downtime-migrations

poetry add django-pg-zero-downtime-migrations

Installing django-pg-zero-downtime-migrations

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.

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

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.

Verify before relying

• Whether idempotent mode (ZERO_DOWNTIME_MIGRATIONS_IDEMPOTENT_SQL) is suitable for production CI pipelines given its reliance on name and constraint state checks rather than full transaction semantics.
• Performance impact of explicit constraint dropping (ZERO_DOWNTIME_MIGRATIONS_EXPLICIT_CONSTRAINTS_DROP) on large tables with many foreign keys.
• Compatibility with PgBouncer transaction pool mode and whether session pool mode is required for timeout settings to function correctly.

Package facts

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

Keywords: django, postgres, postgresql, migrations

Tags

More Database packages