Runbook: Migration Failure Recovery¶

Use this runbook when schema migrations fail in development or release preparation.

Detection Signals¶

• python manage.py migrate exits with error.
• App startup fails with missing table or column errors.
• Divergent migration history between branches.

Recovery Flow¶

flowchart LR
    A[Migration fails] --> B[Inspect migration state]
    B --> C[Identify divergence or bad operation]
    C --> D[Apply corrective migration strategy]
    D --> E[Re-run migration]
    E --> F[Run checks and targeted tests]

Steps¶

1. List migration state: python manage.py showmigrations.
2. Inspect recent migration files and branch history.
3. Resolve ordering/divergence issues via rebase or regenerated migration where appropriate.
4. Re-run migrations.
5. Validate with python manage.py check and targeted tests.

Validation¶

• Migration command completes without errors.
• App checks pass.
• Impacted module tests pass.