Django PG Migrate

1.6.0 · active · verified Sun Apr 12

django-pgmigrate is a Python library that integrates with Django to minimize downtime during PostgreSQL database migrations. It addresses a common issue where long-running transactions can block `python manage.py migrate` operations, causing subsequent queries to queue up. Version 1.6.0 is the current release, and the project is actively maintained with a regular release cadence to support new Django and Python versions. It automatically detects and terminates blocking queries by default, or can be configured to merely show them or set a lock timeout.

Warnings

breaking Python Version Support Drops: Version 1.6.0 dropped support for Python 3.9, and version 1.5.0 dropped Python 3.8. Ensure your Python environment is 3.10 or newer.
Fix: Upgrade Python to 3.10 or later before upgrading django-pgmigrate to versions >= 1.5.0.
breaking Django and PostgreSQL Support Drops: Version 1.4.0 dropped support for Django 3.2 and PostgreSQL 12. Review compatibility notes for each release, as future versions will likely continue to drop older Django and Postgres versions.
Fix: Upgrade Django and PostgreSQL to supported versions (e.g., Django 4.2+ and PostgreSQL 14+ for 1.6.0) before upgrading django-pgmigrate.
gotcha Required `INSTALLED_APPS` Configuration: For `django-pgmigrate` to function, you *must* add `pgactivity`, `pglock`, and `pgmigrate` to your Django project's `INSTALLED_APPS` setting. Failing to do so will result in the features not being active.
Fix: Add 'pgactivity', 'pglock', and 'pgmigrate' to your `INSTALLED_APPS` list in `settings.py`.
gotcha Automatic Blocking Query Termination: By default, `django-pgmigrate` will *automatically terminate* blocking queries during `migrate` operations to avoid downtime. While this is its primary feature, be aware of this behavior. You can configure `PGMIGRATE_BLOCKING_ACTION` in `settings.py` to `pgmigrate.Show` to only display blocking queries, or `None` to disable the action entirely.
Fix: Set `PGMIGRATE_BLOCKING_ACTION = 'pgmigrate.Show'` or `PGMIGRATE_BLOCKING_ACTION = None` in `settings.py` to change default behavior. You can also define custom actions.
gotcha Non-Transactional Migrations: This library applies most SQL fixes outside of transactions (except `RunPython` operations) to prevent deadlocks. If a migration fails mid-way, this design choice means you might need to fix the database state manually, rather than relying on a transaction rollback. It is recommended to keep individual migration files small.
Fix: Design migrations to be as small and atomic as possible to minimize potential mid-failure states. Be prepared for manual database inspection and repair if a non-atomic migration fails.
gotcha Migration Command Patching: `django-pgmigrate` automatically patches the default `migrate` command. If this is undesirable or causes conflicts with other tools, you can disable it by setting `settings.PGMIGRATE_PATCH_MIGRATE = False`. If disabled, you would need to explicitly run the `pgmigrate` management command to utilize its features.
Fix: Set `PGMIGRATE_PATCH_MIGRATE = False` in `settings.py` to disable the patching. You will then need to use `python manage.py pgmigrate` instead of `python manage.py migrate`.

Install

pip install django-pgmigrate Install with pip

Imports

pgmigrate
```
# Add 'pgmigrate' to your INSTALLED_APPS in settings.py
```
This library is primarily integrated by adding its app name to Django's INSTALLED_APPS for its management command patching and settings to take effect. It does not typically require direct code imports for its core functionality.

Quickstart

After installing the library, add `pgactivity`, `pglock`, and `pgmigrate` to your `INSTALLED_APPS` in `settings.py`. Then, simply run `python manage.py migrate` as you normally would. `django-pgmigrate` will automatically detect and terminate blocking queries by default.

# settings.py
INSTALLED_APPS = [
    # ...
    'pgactivity',
    'pglock',
    'pgmigrate',
    # ...
]

# Terminal
# Run Django migrations as usual. django-pgmigrate will automatically handle blocking queries.
# Note: This example does not connect to a live database or create models.
# It only shows the necessary Django settings and command execution.
# For a full setup, ensure your database settings are configured.
# For example, in a local development environment:
# DATABASES = {
#     'default': {
#         'ENGINE': 'django.db.backends.postgresql',
#         'NAME': 'mydatabase',
#         'USER': 'myuser',
#         'PASSWORD': 'mypassword',
#         'HOST': 'localhost',
#         'PORT': '5432',
#     }
# }

# After configuring INSTALLED_APPS, simply run your migrations:
# python manage.py migrate

view raw JSON →