migrations
Migrations: expand-migrate-contract, separate schema vs data migrations, down-migration or explicit irreversible, rollback plan, zombie-code removal.
SKILL.mdskills/backend/migrations/SKILL.md
GitHubmigrations
Migrate without downtime and without fear: expand, move, contract — each step deployable alone.
Activate when
- Changing schemas, backfilling data, renaming fields, or removing old code paths.
Do NOT activate for
- Greenfield schema (see architecture/data-modeling); deploy mechanics (see backend/production-readiness).
Inspection
Current schema, target schema, existing data volume/shape, running application versions, and who reads the changing columns.
Decision rules
- Expand→migrate→contract: additive change first (deploy), backfill + dual-read/write (deploy), cutover + remove old (deploy). Never break the running version in one step.
- Schema migrations separate from data migrations (different failure modes, different rollback).
- Every migration ships a down-path or an explicit irreversible note with owner sign-off; destructive changes (drop column/table) only after the contract phase proves no readers.
- Renames are add-copy-remove, never
RENAMEin one deploy.
Procedure
- Write forward + backward scripts; rehearse on a production-shaped copy.
- Deploy phase by phase with verification gates (row counts, checksums, dual-read agreement).
- Remove the old path + its code (zombie-code sweep) only after cutover metrics confirm.
- Verify: up+down rehearsed, app works at every intermediate phase, rollback drill recorded.
Failure modes
- Locking rewrites on huge tables without batching; backfill without idempotency re-run; dropping columns the old release still reads; untested down-paths.
Escalation
Engine specifics → databases/*; zero-downtime strategy disputes → architecture/api-design (compat) + production-readiness.
References
- Related:
../database-design/,../transactions/,../../databases/fundamentals/.