django-pgmigrate

library1.6.0pypypi✓ verified 24d ago

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.

database devops web-framework

pip install django-pgmigrate

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · DJANGO-PGMIGRATE

django-pgmigrate

databasepythonv1.6.0

Install

3.6s avg

Import

—

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 66.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.6s · import 0.000s · 67MB

66MB installed

● package 66MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

pgmigrate --version

Debug

Known issues

breakingPython 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.

affects: 1.5.0, 1.6.0

breakingDjango 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.

affects: 1.4.0

gotchaRequired `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`.

affects: All

gotchaAutomatic 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.

affects: All

gotchaNon-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.

affects: All

gotchaMigration 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`.

affects: All

Upgrade

Version history

1.6.0latest on PyPI · released Nov 30, 2025

Audit

Dependencies

PythonrequiredRequired for running the library.

DjangorequiredCore framework integration.

Psycopg (psycopg2 or psycopg3)requiredPostgreSQL adapter for Python.

PostgreSQLrequiredTarget database server.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/AmbitionEng/django-pgmigrate ↗

packagehttps://pypi.org/project/django-pgmigrate/ ↗

docshttps://django-pgmigrate.readthedocs.io ↗