Expand and contract

During any rolling deploy, blue-green cutover, or canary, old and new code run simultaneously against the same database, often for minutes and after a rollback for hours.

Every intermediate state must be compatible with both the old and the new version.

A migration correct only after every process restarts causes an outage. This makes ALTER TABLE ... RENAME COLUMN unsafe regardless of how fast it runs: the moment it commits, running old code breaks.

Three phases

1. Expand: add the new thing. Additive only. Old code untouched and unaware.
2. Migrate: write to both, backfill, move readers to the new thing, stop writing the old.
3. Contract: delete the old thing once nothing reads or writes it.

Each phase is at least one deploy, independently deployable and revertible. The gap between phases is where problems surface, so do not compress it.

Schema recipes

Rename a column: six steps