The Database Migration Rule of Three

Three discrete changes for every schema migration: add, dual-write, remove. The pattern that lets you ship migrations without downtime.

The three phases

Phase 1: add the new column / table / index. Old code still uses the old structure.

Phase 2: dual-write. New code writes to both old and new; old code unchanged. Backfill historical data.

Phase 3: remove the old structure. New code reads/writes only the new structure; old code is gone.

Why this works

Zero downtime: at every phase, both old and new code can run. Rollback is always available.

Reversible: phase 1 and 2 can be undone with no data loss. Phase 3 is the only point of no return.

Auditable: each phase is a separate deploy. The team can verify before proceeding.

Pitfalls

Skipping phase 2 because 'this is a small table.' The shortcut is what causes downtime.

Not waiting long enough between phases. Phase 1 → 2 within hours, phase 2 → 3 over weeks for safety.

Forgetting to backfill. The new column is empty for old rows; queries break unexpectedly.