data-migration
Data Migration
The instinct when a schema needs to change is to write one migration that gets the database from old shape to new shape and run it. That instinct is exactly what causes downtime: a single atomic cutover means the old code and the new code cannot both be correct at the same moment, so somewhere in the deploy there is a window where reads or writes are wrong.
The fix is to stop treating "old schema" and "new schema" as two states connected by one migration, and instead treat the migration as a sequence of states where old and new coexist, each individually safe, each individually undoable.
A migration that cannot be paused halfway through, with both old and new still working, is not actually a migration — it is a scheduled outage with a script attached.
For a worked SQL walkthrough of the expand, backfill, and contract phases, read
references/expand-contract.md.