# django-pgmigrate
`django-pgmigrate` helps you avoid costly downtime with Postgres migrations.
Imagine the following happens:
1. A long-running task queries a model in a transaction and keeps the transaction open.
2. `python manage.py migrate` tries to change a field on the model.
Because of how Postgres queues locks, this common scenario causes **every** subsequent query on the model to block until the query from 1) has finished.
`django-pgmigrate` provides the following features to alleviate problematic locking scenarios when running migrations:
* Detect blocking queries and terminate them automatically (the default behavior).
* Print blocking queries so that you can inspect and terminate them manually.
* Set the lock timeout so that migrations are terminated if they block too long.
## Installation
Install `django-pgmigrate` with:
pip3 install django-pgmigrate
After this, add `pgactivity`, `pglock`, and `pgmigrate` to the `INSTALLED_APPS` setting of your Django project.
## Quick Start
After following the installation instructions, running `python manage.py migrate` will automatically terminate any blocking queries. Here's an example of what it looks like:
There are two additional outputs in the `migrate` command versus the original:
1. The first output line shows the Postgres process ID. This is useful for querying activity that's blocking the process.
2. The yellow text shows when a blocking query was detected and terminated. In our case, it was blocking auth migration 12.
You can configure `django-pgmigrate` to show blocked queries instead of automatically killing them, and you can also set the lock timeout to automatically cancel migrations if they block for too long. See the documentation section below for more details.
## Compatibility
`django-pgmigrate` is compatible with Python 3.9 - 3.13, Django 4.2 - 5.1, Psycopg 2 - 3, and Postgres 13 - 17.
## Documentation
[View the django-pgmigrate docs here](https://django-pgmigrate.readthedocs.io) to learn more about:
* How blocking queries are automatically terminated.
* Configuring the command to show blocking activity instead of terminating it, along with instructions on how to manually view and terminate activity.
* Configuring lock timeouts to automatically stop migrations if they block for too long.
* Advanced usage such as creating custom actions to run when queries are blocked.
## Contributing Guide
For information on setting up django-pgmigrate for development and contributing changes, view [CONTRIBUTING.md](CONTRIBUTING.md).
## Creators
- [Wes Kendall](https://github.com/wesleykendall)
- [Paul Gilmartin](https://github.com/PaulGilmartin)
Raw data
{
"_id": null,
"home_page": "https://github.com/AmbitionEng/django-pgmigrate",
"name": "django-pgmigrate",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9.0",
"maintainer_email": null,
"keywords": null,
"author": "Wes Kendall",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f8/db/d19248c5e17babd0fd73bbf93eb0354dc87ee3e29ffe6a9155b165f63d90/django_pgmigrate-1.5.1.tar.gz",
"platform": null,
"description": "# django-pgmigrate\n\n`django-pgmigrate` helps you avoid costly downtime with Postgres migrations.\n\nImagine the following happens:\n\n1. A long-running task queries a model in a transaction and keeps the transaction open.\n2. `python manage.py migrate` tries to change a field on the model.\n\nBecause of how Postgres queues locks, this common scenario causes **every** subsequent query on the model to block until the query from 1) has finished.\n\n`django-pgmigrate` provides the following features to alleviate problematic locking scenarios when running migrations:\n\n* Detect blocking queries and terminate them automatically (the default behavior).\n* Print blocking queries so that you can inspect and terminate them manually.\n* Set the lock timeout so that migrations are terminated if they block too long.\n\n## Installation\n\nInstall `django-pgmigrate` with:\n\n pip3 install django-pgmigrate\n\nAfter this, add `pgactivity`, `pglock`, and `pgmigrate` to the `INSTALLED_APPS` setting of your Django project.\n\n## Quick Start\n\nAfter following the installation instructions, running `python manage.py migrate` will automatically terminate any blocking queries. Here's an example of what it looks like:\n\n\n\nThere are two additional outputs in the `migrate` command versus the original:\n\n1. The first output line shows the Postgres process ID. This is useful for querying activity that's blocking the process.\n2. The yellow text shows when a blocking query was detected and terminated. In our case, it was blocking auth migration 12.\n\nYou can configure `django-pgmigrate` to show blocked queries instead of automatically killing them, and you can also set the lock timeout to automatically cancel migrations if they block for too long. See the documentation section below for more details.\n\n## Compatibility\n\n`django-pgmigrate` is compatible with Python 3.9 - 3.13, Django 4.2 - 5.1, Psycopg 2 - 3, and Postgres 13 - 17.\n\n## Documentation\n\n[View the django-pgmigrate docs here](https://django-pgmigrate.readthedocs.io) to learn more about:\n\n* How blocking queries are automatically terminated.\n* Configuring the command to show blocking activity instead of terminating it, along with instructions on how to manually view and terminate activity.\n* Configuring lock timeouts to automatically stop migrations if they block for too long.\n* Advanced usage such as creating custom actions to run when queries are blocked.\n\n## Contributing Guide\n\nFor information on setting up django-pgmigrate for development and contributing changes, view [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Creators\n\n- [Wes Kendall](https://github.com/wesleykendall)\n- [Paul Gilmartin](https://github.com/PaulGilmartin)\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Avoid costly downtime during Postgres migrations.",
"version": "1.5.1",
"project_urls": {
"Documentation": "https://django-pgmigrate.readthedocs.io",
"Homepage": "https://github.com/AmbitionEng/django-pgmigrate",
"Repository": "https://github.com/AmbitionEng/django-pgmigrate"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7df6767df52ec0a26fb18feed1df6740a1639d5558c4f118fad12802d48f4dfe",
"md5": "8797ce5e0b68d2579334365ed4cd2f45",
"sha256": "dfd4350274aab4fa26a7f0150ea101646ba3751d092715fdd273554dd3ab068e"
},
"downloads": -1,
"filename": "django_pgmigrate-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8797ce5e0b68d2579334365ed4cd2f45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9.0",
"size": 7568,
"upload_time": "2024-12-16T01:55:56",
"upload_time_iso_8601": "2024-12-16T01:55:56.913010Z",
"url": "https://files.pythonhosted.org/packages/7d/f6/767df52ec0a26fb18feed1df6740a1639d5558c4f118fad12802d48f4dfe/django_pgmigrate-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f8dbd19248c5e17babd0fd73bbf93eb0354dc87ee3e29ffe6a9155b165f63d90",
"md5": "449b96abce2eb942648a473e3bc12ed3",
"sha256": "ae1d3f8da2667523f2cf2ffc7a4ee51dccb7811f4883f4f163c4ba083807629f"
},
"downloads": -1,
"filename": "django_pgmigrate-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "449b96abce2eb942648a473e3bc12ed3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9.0",
"size": 7096,
"upload_time": "2024-12-16T01:55:57",
"upload_time_iso_8601": "2024-12-16T01:55:57.824355Z",
"url": "https://files.pythonhosted.org/packages/f8/db/d19248c5e17babd0fd73bbf93eb0354dc87ee3e29ffe6a9155b165f63d90/django_pgmigrate-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 01:55:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AmbitionEng",
"github_project": "django-pgmigrate",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "django-pgmigrate"
}
JSON
