Migration Review

1. Read what it actually does

List every statement and what each one touches. Watch for the ones that hide work:

• A NOT NULL addition with a default may rewrite the whole table.
• A type change may rewrite the whole table.
• An added foreign key takes a lock on both tables and validates every existing row.
• A plain CREATE INDEX holds a write lock for the whole build.

2. Blast radius

For each statement, answer with a number, not an adjective:

• How many rows does it touch?
• What lock does it take, and on what?
• How long will it hold that lock, at production size?
• What queries block behind that lock, and what happens to them? A blocked query usually means a timeout, then a retry storm, then an outage that looks unrelated.

If you cannot answer the timing question, the migration has not been rehearsed and is not ready to approve.

3. Deploy compatibility

The single most common cause of a migration incident. During a deploy, the old code and the new schema coexist, in both orders.

Answer both:

• Does the currently deployed code still work after this migration?
• Does the new code work before it?

If either is no, the change must be split across releases. The general pattern is expand, migrate, contract:

1. Expand. Add the new thing. Nothing reads it yet.
2. Migrate. Backfill, then move readers and writers over.
3. Contract. Remove the old thing, in a later deploy.

Each of these three is a separate, independently deployable change.

4. Backfills

A backfill inside a migration holds a transaction open for its whole duration. Take it out.

• Batch it, with a bounded size per batch and a pause between.
• Make it resumable from a cursor, so an interruption at 60% is not a restart.
• Make it idempotent, so a rerun is harmless.
• Run it separately from the schema change, and monitor it.

5. Rollback

• Is there a down migration, and has it actually been run against a copy?
• If the change is irreversible, is that written down and accepted?
• What is the recovery path if the migration fails halfway through? Know whether your engine wraps DDL in a transaction. Postgres largely does. MySQL largely does not, so a half-applied migration is a real state you must plan for.
• If the answer is "restore from backup", know how long a restore takes and say that out loud before approving.

6. Rehearse

Run it against a restored copy at production scale. Record how long it took. A migration that has never been rehearsed at real size is an estimate, and estimates of lock duration are consistently wrong in the unsafe direction.

7. Approve with the numbers attached

State the row count, the lock, the rehearsed duration, the deploy ordering, and the rollback. An approval without those five is a guess with a signature on it.