By use case
Safe Database Migrations
Ship schema and code changes in stages with guardrail flags so reads and writes remain safe throughout migration windows.
When to use this playbook
- You are introducing a breaking schema change and need compatibility across deploy phases.
- You need to switch read or write paths gradually while monitoring production behavior.
- You want deterministic rollback points if migration performance or correctness degrades.
Migration sequence with rollback safety
- 1. Deploy backward-compatible schema first. Add nullable columns, parallel tables, or non-breaking indexes without changing write behavior yet.
- 2. Gate new writes behind a flag. Enable dual-write or new-write paths for internal traffic only.
- 3. Validate data parity. Compare old and new paths, then ramp write exposure in checkpoints.
- 4. Switch read paths gradually. Move readers to new structures by cohort and monitor latency and error budgets.
- 5. Keep rollback controls until stable. Retain kill switches and fallback defaults until migration confidence is sustained.
Cross-links
Pair migration sequencing with controls.
- Feature Flags for gating read and write path changes.
- Progressive Rollouts for staged exposure by cohort.
- Kill Switches for immediate reversion when anomalies appear.
- Reliability and Operations for production safety posture.
Operational checks before cleanup
- Migration lag is stable and bounded across environments.
- Read and write error rates remain within guardrail thresholds under peak load.
- Rollback paths are documented and tested in staging.
- Temporary migration flags are scheduled for removal after stabilization.