Expand, Migrate, Contract

1. 1
   1. Expand

   Add new_name, nullable, no default. Nothing reads or writes it.

   fails by Adding it NOT NULL or with a volatile default, turning an additive change into a rewrite.

   evidence Column exists; no change in error rate or latency.

2. 2
   2. Deploy dual-write code

   Every write path writes both columns; all reads still use old_name.

   fails by A write path nobody remembered — an admin tool, an importer, a consumer of a queue.

   evidence Count of rows with new_name populated rises with write volume, from every path.

3. 3
   3. Backfill

   Copies historical rows into new_name in batches, throttled against replication lag.

   fails by One statement over the whole table; no resume point after a failure (Backfills).

   evidence Zero rows remain where old_name is set and new_name is not.

4. 4
   4. Switch reads

   Reads move to new_name, behind a flag so the switch is reversible in seconds.

   fails by Shipping the switch as a deploy, so reverting it needs a rollout during an incident.

   evidence Endpoint error rate and latency unchanged against baseline; the flag has been flipped back and forth once, deliberately.

5. 5
   5. Verify

   Confirms nothing still reads or depends on old_name, across every deployable and every scheduled job.

   fails by Verifying by reading code instead of by measuring the running system.

   evidence A counter on the old read path has been zero for longer than the lifetime of your longest-lived job (Cron Jobs in Production).

6. 6
   6. Contract

   Stop writing old_name, then drop it — in a separate, later release.

   fails by Shipping it with step 4. This is the failure the whole pattern exists to prevent.

   evidence Column gone; error rate flat; and you already know nothing referenced it, because step 5 proved it (Destructive Migrations).

Steps 1–2 may ship together only if the migration runs strictly before the new code starts. Steps 4 and 6 must not, under any circumstances, share a release.

1. Release 1changeMigration adds nullable new_name. No code changes. Additive, inert, reversible by ignoring it.
2. Release 1 + rolloutsignalNothing observable happens. This is the correct outcome of an expand step.
3. Release 2changeCode deploys that writes both columns and reads old_name. During the rollout, some instances write one column and some write two — both states are valid.
4. Release 2 + rolloutsignalDual-write coverage metric climbs to 100% of writes as the last old instance is replaced.
5. Backfill windowactionBatched backfill runs against live traffic, throttled on replication lag. It can be paused, resumed, and re-run; new writes are already covered by dual writes.
6. VerificationsignalCompleteness query returns zero remaining rows. A sampled consistency check finds no divergence between the two columns.
7. Release 3changeReads switch to new_name via a flag, ramped rather than flipped. old_name is still written and still correct, so the flag is a real revert path.
8. SoaksignalThe old read path counter goes to zero and stays there, across at least one full cycle of every scheduled job.
9. Release 4changeDual writes removed. old_name is now stale but still present — deliberately, for one more release.
10. Release 5recoveryDROP COLUMN old_name. Irreversible, and by now boring.

The gap between release 3 and release 5 exists so that a rollback to release 2 remains possible for as long as anyone might want one. Contracting early does not make the change finish sooner; it makes the rollback path disappear while you still need it.

migration:  ALTER TABLE users RENAME old_name TO new_name;
code:       reads and writes new_name

deploy:
  t0  migration applies
  t0  every running instance is old code -> queries old_name -> ERROR
  t1  first new instance starts serving correctly
  t2  ... rollout continues, error rate proportional to remaining old instances
  t3  rollout completes, errors stop
  rollback? old artifact fails against the new schema too.

release 1  add new_name (nullable)          -> nothing reads it
release 2  write both, read old_name         -> both states valid
backfill   batched, throttled, resumable     -> no schema change
release 3  read new_name behind a flag       -> revert = flip flag
release 4  stop writing old_name             -> still present
release 5  drop old_name                     -> irreversible, and safe

Not because it is tidier — because in the second version there is no moment at which the deployed code and the schema disagree. The error window in the first version is exactly the duration of the rollout, and its rollback path is broken in both directions.