Parallel change, also called expand-contract, keeps a live schema compatible while replacing a structure in stages. Instead of altering a busy table once, add the new column or table, write to both versions, backfill existing data, switch reads, and remove the original later. section 7.7
Use the migration history to recognize an incomplete or safe rollout:
- A single change scattered across several migration files can indicate a safe rollout in progress. section 7.7
- Duplicate old and new fields may indicate that the final removal step never happened. section 7.7
- When migration history is unavailable, follow the schema file through git commits rather than trusting a squashed directory. section 7.7
Replacing a column safely
Add the replacement column, dual-write old and new columns, backfill existing rows, migrate reads, then drop the original column in a later migration. GitHub's gh-ost is one tool for executing this kind of rollout. section 7.7
Figure 7.8 The migration folder tells the story that the final schema erases. On the left, migrations from August 2021 to March 2023 add tables for team features (Team, Payment, Workflow). On the right, a pivot to enterprise features begins in May 2023 with the Organization table. This history is obvious when reading the migrations in order but invisible in the current schema.

Migration chronology reveals staged schema changes and abandoned intermediate structures that the final schema conceals. section 7.7

