{"id":4513,"library":"django-pgmigrate","title":"Django PG Migrate","description":"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.","status":"active","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/AmbitionEng/django-pgmigrate","tags":["django","postgres","migrations","database","downtime","zero-downtime"],"install":[{"cmd":"pip install django-pgmigrate","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for running the library.","package":"Python","version":">=3.10.0, <4"},{"reason":"Core framework integration.","package":"Django","version":"4.2 - 6.0"},{"reason":"PostgreSQL adapter for Python.","package":"Psycopg (psycopg2 or psycopg3)","version":"2 - 3"},{"reason":"Target database server.","package":"PostgreSQL","version":"14 - 18"}],"imports":[{"note":"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.","symbol":"pgmigrate","correct":"# Add 'pgmigrate' to your INSTALLED_APPS in settings.py"}],"quickstart":{"code":"# settings.py\nINSTALLED_APPS = [\n    # ...\n    'pgactivity',\n    'pglock',\n    'pgmigrate',\n    # ...\n]\n\n# Terminal\n# Run Django migrations as usual. django-pgmigrate will automatically handle blocking queries.\n# Note: This example does not connect to a live database or create models.\n# It only shows the necessary Django settings and command execution.\n# For a full setup, ensure your database settings are configured.\n# For example, in a local development environment:\n# DATABASES = {\n#     'default': {\n#         'ENGINE': 'django.db.backends.postgresql',\n#         'NAME': 'mydatabase',\n#         'USER': 'myuser',\n#         'PASSWORD': 'mypassword',\n#         'HOST': 'localhost',\n#         'PORT': '5432',\n#     }\n# }\n\n# After configuring INSTALLED_APPS, simply run your migrations:\n# python manage.py migrate\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.10 or later before upgrading django-pgmigrate to versions >= 1.5.0.","message":"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.","severity":"breaking","affected_versions":"1.5.0, 1.6.0"},{"fix":"Upgrade Django and PostgreSQL to supported versions (e.g., Django 4.2+ and PostgreSQL 14+ for 1.6.0) before upgrading django-pgmigrate.","message":"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.","severity":"breaking","affected_versions":"1.4.0"},{"fix":"Add 'pgactivity', 'pglock', and 'pgmigrate' to your `INSTALLED_APPS` list in `settings.py`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}