| name | migration-helper |
| description | Guide safe database and code migrations with zero-downtime strategies. |
| autoInvoke | false |
| priority | medium |
| triggers | ["database migration","code migration","zero-downtime"] |
| user-invocable | false |
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
- Always backup before migration
- Test on staging first
- Make migrations reversible
- Deploy in small batches
- 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'`);
}
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.
Rollback Strategies
| Strategy | When |
|---|
| Script rollback | Reversible data changes |
| Backup restore | Major failure |
| Feature flag off | Code changes |
| Traffic reroute | Service migration |