django-safe-migration

What this skill does

# Django Migration — Zero Downtime

## Project Configuration

Read the project's `CLAUDE.md` or `AGENTS.md` for the values below. If they are not set, use the defaults shown.

| Key | Default | Notes |
|---|---|---|
| **Django version** | unknown | Affects `db_default` availability — only Django 5.0+ supports it |
| **Deploy strategy** | rolling deploy | Rolling deploy is the most restrictive; blue/green or maintenance-window deploys allow more operations |
| **Runtime guard** | none | If a guard is configured (e.g. `django-pg-zero-downtime-migrations`), operations it blocks are **Errors**; uncovered operations are **Warnings** |
| **Migration command** | `python manage.py sqlmigrate` | e.g. `make sqlmigrate` or `docker compose run web python manage.py sqlmigrate` |
| **Docs / wiki URL** | none | If set, append `#<anchor>` links when flagging issues in review output |

To configure this skill for your project, add a section like this to your `CLAUDE.md` or `AGENTS.md`:

```
## django-safe-migration
- Django version: 5.1
- Deploy strategy: rolling deploy
- Runtime guard: none
- Migration command: docker compose run web python manage.py sqlmigrate
- Docs URL: https://github.com/your-org/repo/wiki/migrations
```

---

## When to Use

- "Review this migration"
- "Is this migration safe?"
- "Write a migration for..."
- "Rewrite this migration to be safe"
- "How do I add a NOT NULL column / drop a column / add an index / rename a column / add a FK..."

---

## Why Zero-Downtime Migrations Matter

In a rolling deploy, the new database schema is applied first, then application instances are restarted one by one. At any moment during the deploy, old code and new code run simultaneously against the same database.

Every migration must be safe to run while the previous version of the app is still serving traffic. A migration that takes an `ACCESS EXCLUSIVE` lock on a large table blocks all reads and writes — downtime even for a few seconds on a busy table.

The problem is not just the lock itself but the **wait queue**: a fast `ALTER TABLE` that takes 50ms will queue behind any long-running transaction, and all subsequent queries queue behind the migration. On a busy table this cascades into connection pool exhaustion.

---

## How PostgreSQL Locking Works

| Lock | Acquired by | Blocks |
|---|---|---|
| `ACCESS EXCLUSIVE` | Most `ALTER TABLE`, `DROP INDEX`, `DROP CONSTRAINT` (FK) | All reads and writes |
| `SHARE ROW EXCLUSIVE` | `ADD FOREIGN KEY` (on child table + referenced table simultaneously) | Writes only (on both tables) |
| `SHARE` | `CREATE INDEX` | Writes only |
| `SHARE UPDATE EXCLUSIVE` | `CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT` | Nothing meaningful — safe under traffic |

For the full conflict matrix (table-level locks × business logic operations × row-level locks) and the FIFO wait-queue explanation, load `references/postgres-locks.md`. Load it when:
- explaining *why* a specific operation is unsafe
- a developer asks what a lock type blocks or conflicts with
- reasoning about whether two concurrent operations interact

---

## lock_timeout

Any operation that requires `ACCESS EXCLUSIVE` should be preceded by `SET LOCAL lock_timeout`. This causes the migration to fail fast (with a clear error) instead of waiting indefinitely for the lock — preventing connection pool exhaustion from queue cascading.

For a normal transactional migration:

```python
migrations.RunSQL("SET LOCAL lock_timeout = '2s'"),
migrations.AlterField(...),  # or any ACCESS EXCLUSIVE operation
```

`SET LOCAL` scopes the timeout to the current transaction, so it does not affect other sessions or persist after the migration completes.

**Default**: `2s` — adjust up if the table is known to have long-running transactions that legitimately need more time, or down for stricter environments.

For `atomic = False` migrations, combine `SET LOCAL` and the DDL in the same `RunSQL` operation; see Structural Rules below.

---

## Key Patterns

### NOT VALID + VALIDATE (for FK and CHECK constraints)

A two-step PostgreSQL technique to add a constraint without a long lock:

1. **`ADD CONSTRAINT … NOT VALID`** — creates the constraint and enforces it on new writes immediately, but skips scanning existing rows. Takes a brief lock with no table scan — `SHARE ROW EXCLUSIVE` on both tables for FK constraints, `ACCESS EXCLUSIVE` for CHECK constraints.
2. **`VALIDATE CONSTRAINT`** — scans existing rows to confirm they satisfy the constraint. Takes `SHARE UPDATE EXCLUSIVE` (plus `ROW SHARE` on the referenced table for FK constraints), which does not block reads or writes.

The dangerous part is the full-table scan, not the constraint creation itself. Splitting it keeps the write-blocking lock window to milliseconds, with the long scan moved to a non-blocking step.

PostgreSQL docs: [`NOT VALID`](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-DESC-ADD-TABLE-CONSTRAINT) · [`VALIDATE CONSTRAINT`](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-DESC-VALIDATE-CONSTRAINT)

---

## Runtime Guards

Some projects configure a custom database backend or linter that raises errors for unsafe operations at migration time (e.g. `zero_downtime_migrations`, `django-pg-zero-downtime-migrations`, `django-migration-linter`).

When reviewing a migration:
- Operations the project's runtime guard **blocks** → classify as **Error** (migration will not run)
- Operations the guard **does not cover** → classify as **Warning** (migration runs but may cause downtime)

If no runtime guard is configured, treat all unsafe operations as **Errors** that require a safe rewrite before deploying to production.

Check the Project Configuration block above (or `AGENTS.md`) for what this project's guard covers.

---

## Mode 1: Review

### Goal
Identify every operation that is unsafe or risky for a rolling deploy on PostgreSQL.

### Steps

1. Read the migration file in full.
2. Run `<migration_command> <app_label> <migration_name>` to get the actual SQL Django will execute. **Always do this — the generated SQL is the ground truth.** Use the `Migration command` value from `CLAUDE.md`/`AGENTS.md`; default is `python manage.py sqlmigrate`. If the key is not set and a `Makefile` or `docker-compose.yml` exists in the project root, ask the user: "How do you run sqlmigrate in this project?" and suggest they save the answer to `CLAUDE.md`. The ORM operation class alone is not sufficient: for example, `AlterField` on a FK field that adds `null=True` also drops and re-adds the FK constraint, emitting `DROP CONSTRAINT` (taking `ACCESS EXCLUSIVE` on both the child and referenced table) followed by `ADD CONSTRAINT FOREIGN KEY` without `NOT VALID` (taking `SHARE ROW EXCLUSIVE` with a full scan on both tables) — neither is visible from the migration file alone.
3. Load `references/operation-guide.md`. Load `references/postgres-locks.md` when explaining why a flagged operation is unsafe.
4. For each SQL statement produced, check it against the detection checklist below.
5. If any operation requires `ACCESS EXCLUSIVE` (flagged as error or warning), ask the user before outputting the report:
   > "This migration contains an `ACCESS EXCLUSIVE` operation. A `lock_timeout` should be added to fail fast instead of queuing and cascading. The default is `2s` — confirm or provide a custom value."
   If the migration already contains `SET LOCAL lock_timeout`, note the existing value and ask the user to confirm it is appropriate.
   Use the confirmed value in the fix instructions.
6. Output a structured report:

## Migration Review: <filename>

### Errors — will cause downtime or be blocked by runtime guard
- [ERROR] `<OperationClass>` on `<app>.<Model>.<field>`: <what it does and why it's unsafe>
  Fix: <one-sentence description of the safe alternative>
  What this rewrite changes: clarify whether `ACCESS EXCLUSIVE` is still required in the safe version, and if so, explain what actually improves —