DB Migration Safety

Overview

The two failure modes this guards against: a migration that locks a large table for the duration of a deploy (site goes down), and a migration that succeeds but corrupts or loses data because it wasn't idempotent or wasn't backed up. Neither is recoverable by "just re-running the migration" — the first needs the expand-contract pattern, the second needs a MANDATORY backup confirmation before anything touches production.

The expand-contract pattern

Never do add-column + backfill + make-required in one migration against a live table with real traffic. Split into phases, each independently deployable:

1. Expand — add the new column/table as nullable or with a default, additive only. Old code keeps working unmodified.
2. Backfill — populate the new column for existing rows, in batches (see below), running alongside live traffic.
3. Migrate reads/writes — deploy application code that writes to (and eventually reads from) the new shape. Both old and new columns may coexist briefly.
4. Contract — once all app instances are on the new code path and backfill is confirmed complete, drop the old column / add the NOT NULL constraint / drop the old table.

Each phase is its own migration and its own deploy. Collapsing steps 1 and 4 into one migration is the single most common cause of an avoidable outage.

Workflow