Migration Safety

Purpose

A schema migration is one of the few changes in a backend codebase that's genuinely hard to undo once it's run against production data. This skill is a checklist for writing migrations that are safe to ship: they roll back cleanly, they don't quietly lock a hot table, and they never get hand-edited after the fact.

When to use it

Every time a change requires adding, altering, or removing a table, column, index, or constraint — not just for "big" migrations. Small migrations cause outages just as often as big ones; the discipline should be automatic, not reserved for changes that look risky.

The working-rollback requirement

• Write downgrade() (or your migration tool's equivalent) at the same time as upgrade(), not as a stub to fill in later.
• Actually run the rollback locally against a database that has the upgrade applied, and confirm the schema afterward matches pre-migration state. A downgrade() that's never been executed is unverified code, no different from an untested code path anywhere else.
• If a migration is genuinely irreversible (e.g. it drops a column and the data is gone), say so explicitly in the migration and think hard about whether that's really necessary now, versus deprecating the column first and dropping it in a later, separate migration once you're sure nothing needs it.

Never edit a committed migration

• Once a migration has been merged (and especially once it's been applied anywhere outside your own branch), treat the file as immutable. If you find a mistake, write a new migration that corrects it — don't go back and change the original.
• Editing an already-applied migration means the migration history table (whatever tracks "which migrations have run") no longer matches what the file actually says, which silently desyncs anyone who already ran the old version from anyone running the edited one. This is one of the few migration mistakes that's genuinely hard to recover from cleanly.

Locking and performance review