The three-phase pattern that lets a schema change ship on a Tuesday afternoon, with no maintenance window.
Executive Summary
- A schema change only needs a maintenance window when write and read are coupled; the expand-migrate-contract pattern decouples them.
- Backfill in bounded batches behind a feature flag, so a slow migration degrades throughput instead of taking the service down.
- Keep the old column readable until every deployed instance has been reading the new one for a full release cycle.
Where teams usually start
Most teams arrive at this problem from the same direction: something that worked at one scale stopped working at the next, and the fix that used to be obvious no longer is. This guide walks the path we take with clients, in the order we take it.
The approach
Work in slices that can each ship on their own. A slice that cannot be deployed independently is not a slice, it is a phase – and phases are where migrations go to die.
What to measure
Decide the numbers that say it worked before you start, and instrument them first. Retrofitting measurement onto a finished migration tells you nothing about what the migration changed.
Conclusion
None of this is exotic. It is the discipline of small, reversible steps applied to a problem large enough that skipping the discipline is tempting.
