Lesson 2 — The Expand–Contract Pattern

Expand–contract is the workhorse of zero-downtime migrations. The idea is to treat a schema change not as one operation but as four: expand the schema additively, deploy application code that tolerates both the old and the new shape, backfill the new shape from the old one, and finally contract the schema by removing whatever the old shape occupied.

The discipline is that every phase has to be independently safe to roll back. If phase 2 goes wrong, you should be able to revert the application code without touching the database at all. If phase 3 goes wrong, you should be able to stop and restart the backfill without the application noticing. Phase 4 — the destructive one — comes last, and only after the system has been stable on the new shape for long enough that you trust it.

The classic example is a column rename. You add the new column (expand). You update application code to write both columns (deploy). You run a backfill from old to new (backfill). You update code to read the new column. Then — and only then — you drop the old column (contract). It feels like overkill the first time. The third time you do it, it feels like the only way anything ever changes.