Workflows
Database Migration Safety Workflow
Reduce schema-change risk by splitting migrations into reversible, observable stages instead of one irreversible release step.
- Teams turning commands into repeatable routines
- Readers who need sequencing, branch, and sync discipline
- Basic understanding of fetch, pull, push, and branches
- A sense of how and why branches diverge
- Copying a workflow without checking branch state
- Choosing the wrong integration path on shared branches
Database migration failures often cost more than application rollback failures. Safe migration design is about reversible sequencing, not just SQL correctness.
Recommended sequence
1. Expand: add structures before removing legacy paths
Keep existing behavior valid while introducing new schema.
2. Backfill: migrate historical data gradually
Throttle data jobs to avoid lock and load spikes.
3. Switch: move reads/writes in controlled phases
Use shadow reads or dual-write windows before full switch.
4. Contract: remove old paths only after steady state
Delay destructive cleanup until after multiple stable release cycles.
Pre-release checklist
- explicit rollback method exists
- lock/slow-query monitoring is enabled
- migration window avoids peak traffic
- pre-production rehearsal matches realistic data volume
Deleting old columns before complete end-to-end cutover makes rollback significantly harder.
Common mistakes
Mistake 1: assuming dev-scale tests predict production behavior
Production data shape and volume expose different locking and performance risks.
Mistake 2: tightly coupling migration and app rollout
Prefer staged deployability where migration can precede application path switch.
Mistake 3: rollback plan written as a vague sentence
Rollback must be explicit, procedural, and testable.
- Define expand/backfill/switch/contract actions.
- Define observable metrics for each stage.
- Define rollback path for each stage.
- Rehearse with near-production data volume.
Good follow-up reads
Code freeze and release candidate workflowRelease branch workflowHotfix rollback after release