the pipeline · migrations
Migration discipline
The schema was shaped in Volume III. Now it has to reach production safely. A schema migration that locks a table for thirty seconds during peak traffic is a production incident. A migration that drops a column before the code stops using it is data loss. The discipline is not about the migration tool — it is about the order of operations.
- Backward-compatible first. Every migration must work with both the old code and the new code running simultaneously. Add columns before using them. Stop using columns before removing them. Two deploys, not one.
- Data backfills are separate. A migration changes the schema. A backfill populates data. They are different operations with different risk profiles. Backfills run in staging first, with timing recorded, before running in production.
- Migration testing in staging. Every migration runs against a staging database with production-scale data before it touches production. The time it takes is measured. If it takes more than acceptable downtime, the migration is redesigned.
- Rollback plan written before migration runs. What happens if the migration fails halfway? For additive changes (new columns, new tables), rollback is dropping what was added. For destructive changes (column removal, type change), rollback may require a data restore. The plan is written, reviewed, and tested before the migration runs in production.
Resolution gate — Pipeline to Testing
Enough to know which kind of failure to fix.
Every commit reaches the pipeline. Every stage catches a distinct category of failure. Migrations are backward-compatible and tested in staging. Secrets never reach the repository.
Test: when a developer sees a red build, they know which level of the chain to investigate before they look at the code.