Registry / database / django-pg-migration-tools

django-pg-migration-tools

JSON →
library0.1.26pypypiunverified

django-pg-migration-tools is a Python library that provides a set of specialized Django migration operations designed to make database schema changes safer and more scalable on PostgreSQL. It includes tools for idempotent model creation, concurrent index and constraint management, function migration, and concurrent column alterations, aiming to minimize downtime and avoid common locking issues during deployments. The current version is 0.1.26, and it typically sees releases for new features or bug fixes rather than a fixed cadence.

pip install django-pg-migration-tools
INSTALL
IMPORT
SIG · DJANGO-PG-MIGRATIO
D
django-pg-migration-tools
databasepythonv0.1.26
Install
1.5s avg
Import
Disk
15MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.26 · 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
glibc
py 3.10
✓ —
✓ 1.5s
py 3.11
✓ —
✓ 1.65s
py 3.12
✓ —
✓ 1.45s
py 3.13
✓ —
✓ 1.45s
py 3.9
✕ build_error
✕ build_error
15MB installed
● package 15MB
Code
Verified usage

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

CreateModelIfNotExists
from django_pg_migration_tools.operations import CreateModelIfNotExists
from django_pg_migration_tools import CreateModelIfNotExists

This quickstart demonstrates how to use `AddIndexConcurrently` within a Django migration. Note that for any 'CONCURRENTLY' operation, the migration must set `atomic = False`. This example assumes you have a Django project and an app named `your_app_name` with a model `yourmodelname` and a `field_name`.

import os from django.db import migrations, models from django_pg_migration_tools.operations import AddIndexConcurrently # Example of a Django migration using AddIndexConcurrently # This migration file would typically be in app_name/migrations/000X_... class Migration(migrations.Migration): atomic = False # Required for CONCURRENTLY operations dependencies = [ ('your_app_name', '0001_initial'), # Replace with your actual dependency ] operations = [ # Add a B-tree index concurrently on 'field_name' of 'model_name' AddIndexConcurrently( model_name='yourmodelname', name='yourmodelname_field_name_idx', fields=['field_name'], db_tablespace='', # Optional: specify tablespace opclasses=[], # Optional: specify opclasses for the index condition=None # Optional: specify a partial index condition ), # Other operations could follow ]
Debug
Known issues
gotchaOperations ending in 'Concurrently' (e.g., `AddIndexConcurrently`) require careful consideration. They leverage specific PostgreSQL features that prevent them from running within a transaction block. You must set `atomic = False` in your `Migration` class for these to work, which means the entire migration is not atomic.
fix
Add `atomic = False` as a class attribute to your `migrations.Migration` class: `class Migration(migrations.Migration): atomic = False`.
affects: All versions
gotchaIgnoring the `PostgreSQLCheck` can lead to issues. The library provides `django_pg_migration_tools.checks.PostgreSQLCheck` to identify and warn about common footguns when using its operations, especially regarding concurrent operations being blocked by active transactions. It is recommended to include this check.
fix
Add `'django_pg_migration_tools.checks.PostgreSQLCheck'` to your Django `settings.py` `SILENCED_SYSTEM_CHECKS` or explicitly run it during development/testing. Ensure you understand its warnings.
affects: All versions
breakingAs a pre-1.0 library (currently 0.1.x), the API surface can change between minor versions (e.g., 0.1.25 to 0.1.26) without explicit deprecation warnings or major announcements for less commonly used features. Always review the GitHub changelog or release notes before upgrading to avoid unexpected breaks.
fix
Consult the project's GitHub releases page or `pyproject.toml`/`setup.py` for specific changes before upgrading. Pin your dependency versions to prevent automatic updates.
affects: < 1.0.0
Upgrade
Version history
0.1.26latest on PyPI · released Feb 27, 2026
Audit
Dependencies
DjangorequiredCore framework integration
psycopg2-binaryrequiredPostgreSQL database adapter
Agent activity
16 hits · last 30 days
node
16
Resources
django-pg-migration-tools — pip install django-pg-migration-tools · libregistry