django-migration-psql

When to use

• Creating a new Django migration
• Running makemigrations or pgmakemigrations
• Reviewing a PR that adds or modifies migrations
• Adding indexes, constraints, or models to the database

Why this matters

A bad migration can lock a production table for minutes, block all reads/writes, or silently skip index creation on partitioned tables.

Auto-generated migrations need splitting

makemigrations and pgmakemigrations bundle everything into one file: CreateModel, AddIndex, AddConstraint, sometimes across multiple tables. This is the default Django behavior and it violates every rule below.

After generating a migration, ALWAYS review it and split it:

1. Read the generated file and identify every operation
2. Group operations by concern:
   • CreateModel + AddConstraint for each new table → one migration per table
   • AddIndex per table → one migration per table
   • AddIndex on partitioned tables → two migrations (partition + parent)
   • AlterField, AddField, RemoveField for each table → one migration per table
3. Rewrite the generated file into separate migration files with correct dependencies
4. Delete the original auto-generated migration

When adding fields or indexes to an existing model, makemigrations may also bundle AddIndex for unrelated tables that had pending model changes. Always check for stowaways from other tables.

Rule 1: separate indexes from model creation

CreateModel + AddConstraint = same migration (structural). AddIndex = separate migration file (performance).

Django runs each migration inside a transaction (unless atomic = False). If an index operation fails, it rolls back everything, including the model creation. Splitting means a failed index doesn't prevent the table from existing. It also lets you --fake index migrations independently (see Rule 4).

Bad

# 0081_finding_group_daily_summary.py — DON'T DO THIS
class Migration(migrations.Migration):
    operations = [
        migrations.CreateModel(name="FindingGroupDailySummary", ...),
        migrations.AddIndex(model_name="findinggroupdailysummary", ...),  # separate this
        migrations.AddIndex(model_name="findinggroupdailysummary", ...),  # separate this
        migrations.AddConstraint(model_name="findinggroupdailysummary", ...),  # this is fine here
    ]