migration-helper

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Skill: Migration Helper

Safe database and code migrations with zero-downtime strategies.

---

Safety Rules

1. Always backup before migration
2. Test on staging first
3. Make migrations reversible
4. Deploy in small batches
5. Monitor during migration

---

Related Rules

• rules/core/simplicity-over-complexity.md — smallest migration that closes the gap; no "while we're here" schema expansions
• rules/core/verification.md — verify each migration step before advancing
• rules/workflow/immutable-workflow.md — migrations are append-only records
• rules/workflow/dual-llm-review.md — destructive migrations (DROP COLUMN/TABLE) trigger dual-LLM review

---

Schema Changes

Change	Safe Approach
Add column	Add nullable → backfill → NOT NULL
Remove column	Stop using → deploy → drop
Rename column	Add new → copy → deploy → drop old
Add index	CREATE INDEX CONCURRENTLY
Change type	Add new col → migrate → drop old

Zero-Downtime (6 phases)

Add nullable → dual-write → backfill → switch reads → remove old writes → drop old column.

---

Migration Script Pattern

export async function up(db: Database) {
  await db.query(`ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active'`);
  // Backfill in batches of 1000
  // Add NOT NULL constraint
}
export async function down(db: Database) {
  await db.query(`ALTER TABLE users DROP COLUMN status`);
}

---

Code Migration

• Feature flags: Behind flag → gradually increase % → remove flag + old code
• Strangler Fig: New impl alongside old → route traffic gradually → remove old

---

Checklist

Before: Backup, tested on staging, rollback plan, monitoring alerts. During: Batch processing, monitor performance, verify integrity. After: Validation queries, smoke tests, monitor 24-48h, document.