Registry /
database / django-pg-zero-downtime-migrations
Install & Compatibility
Where this runs
tested against v0.19 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DATABASES['default']['ENGINE']
✓ DATABASES = {
'default': {
'ENGINE': 'django_pg_zero_downtime_migrations.backends.postgres',
...
}
}
✗ 'ENGINE': 'django.db.backends.postgresql'
The core usage involves replacing the default PostgreSQL engine with the provided zero-downtime backend in Django settings.
To enable zero-downtime migrations, configure your Django `DATABASES` setting to use the library's PostgreSQL backend. Additionally, it's highly recommended to set specific timeouts and enable raising errors for unsafe operations to enforce zero-downtime principles.
import os
DATABASES = {
'default': {
'ENGINE': 'django_pg_zero_downtime_migrations.backends.postgres',
'NAME': os.environ.get('DB_NAME', 'your_database_name'),
'USER': os.environ.get('DB_USER', 'your_user'),
'PASSWORD': os.environ.get('DB_PASSWORD', 'your_password'),
'HOST': os.environ.get('DB_HOST', 'localhost'),
'PORT': os.environ.get('DB_PORT', '5432'),
}
}
# Recommended settings for zero-downtime operations
ZERO_DOWNTIME_MIGRATIONS_LOCK_TIMEOUT = '2s'
ZERO_DOWNTIME_MIGRATIONS_STATEMENT_TIMEOUT = '2s'
ZERO_DOWNTIME_MIGRATIONS_FLEXIBLE_STATEMENT_TIMEOUT = True
ZERO_DOWNTIME_MIGRATIONS_RAISE_FOR_UNSAFE = True
# For Django < 5.0 when adding columns with code defaults
# ZERO_DOWNTIME_MIGRATIONS_KEEP_DEFAULT = True
Debug
Known issues
breakingThis library frequently drops support for older Django, Python, and PostgreSQL versions. For example, version 0.17 dropped Django 3.2, 4.0, 4.1 and Python 3.6, 3.7. Version 0.14 dropped PostgreSQL 11 and the setting `ZERO_DOWNTIME_MIGRATIONS_USE_NOT_NULL`.fixReview the release notes for your target `django-pg-zero-downtime-migrations` version to ensure compatibility with your environment. Upgrade Django, Python, or PostgreSQL as needed, or pin the library to a compatible older version.
affects: 0.12, 0.13, 0.14, 0.17 onwards
deprecatedThe `migrate_isnotnull_check_constraints` command was marked deprecated in 0.14 and completely dropped in 0.17.fixRemove any calls to this command. The library now handles `NOT NULL` constraint creation and validation internally as part of its zero-downtime strategy using `CHECK` constraints.
affects: 0.14 (deprecated), 0.17 (removed)
gotchaThe backend does not use transactions for schema migrations (except for `RunPython` operations) to avoid deadlocks for complex migrations. If a schema migration fails mid-operation, the database state might be inconsistent, requiring manual intervention.fixKeep individual migration files small and focused. Thoroughly test migrations in a staging environment that mirrors production. Always have a database backup and a rollback plan. Monitor migrations closely during deployment.
affects: All versions
gotchaAdding a `NOT NULL` column with a code-level default (e.g., `default=...` in a Django model field) can still cause downtime issues in older Django versions. PostgreSQL will attempt to fill existing rows, acquiring a table lock. While the library makes `ADD COLUMN DEFAULT NOT NULL` safe for Django 5.0+ with `db_default` and offers `ZERO_DOWNTIME_MIGRATIONS_KEEP_DEFAULT` for older Django versions, manual steps are safer if not properly configured.fixFor Django < 5.0, consider setting `ZERO_DOWNTIME_MIGRATIONS_KEEP_DEFAULT = True` in your settings. For maximum safety, add new columns as nullable first, deploy code that populates the column for existing data, and then create a subsequent migration to set the column as `NOT NULL`.
affects: Prior to 0.16, and Django versions before 5.0 without `db_default`.
Upgrade
Version history
0.19latest on PyPI · released Jun 6, 2025
Audit
Dependencies
DjangorequiredThis is a Django backend; specific Django versions are supported per library release.
PostgreSQLrequiredThis library is a PostgreSQL-specific backend; specific PostgreSQL versions are supported per library release.