Migrate

Migration Planning

Migrations are the most dangerous routine operation in software. Plan carefully, execute incrementally, always have a rollback.

Before Starting

1. Inventory what's affected. Every table, endpoint, consumer, job, cache that touches the thing being migrated.
2. Define success criteria. How do you know the migration worked? What metrics must stay stable?
3. Plan rollback. If it goes wrong at step 5 of 10, how do you undo? If you can't answer this, you're not ready.
4. Estimate downtime. Zero-downtime? Maintenance window? Communicate to stakeholders.

Migration Types

Database Schema Migration

1. Write migration script (up + down)
2. Test on a copy of production data
3. Measure execution time on production-sized dataset
4. Deploy new code that handles BOTH old and new schema
5. Run migration
6. Verify data integrity
7. Remove old-schema compatibility code
8. Drop old columns/tables (after grace period)

Rules:

• Never rename a column in one step. Add new → backfill → deploy code using new → drop old.
• Never drop a column the same deploy as the code change. Wait one release cycle.
• Always test with production-scale data. A migration that takes 1s on 1K rows might take 2h on 10M.
• Lock-free migrations for large tables (add column with default, backfill in batches).

API Version Migration

1. Ship new version alongside old (v1 + v2)
2. Update clients to use v2
3. Monitor v1 traffic → 0
4. Deprecation notice with deadline
5. Remove v1 after deadline

Rules:

• Never break existing clients without warning.
• Version in URL path (/v2/) or header, not query param.
• Log which version each client uses for migration tracking.

Dependency / Framework Upgrade

1. Read changelog for breaking changes
2. Check if your usage hits any breaking changes
3. Upgrade in an isolated branch
4. Fix compilation/type errors
5. Run full test suite
6. Test manually for behavioral changes not caught by tests
7. Deploy to staging, soak for 24h
8. Deploy to production

Rules:

• Upgrade one major dependency at a time. Never batch major upgrades.
• Pin exact versions. Update deliberately, not automatically.
• Check transitive dependency conflicts.

System / Platform Migration

1. Run old and new in parallel (shadow mode)
2. Compare outputs - they must match
3. Gradually shift traffic (1% → 10% → 50% → 100%)
4. Monitor error rates, latency, and correctness at each step
5. Keep old system running for quick rollback
6. Decommission old system after confidence period

Migration Checklist

• [ ] Rollback plan documented and tested
• [ ] Success criteria defined with specific metrics
• [ ] Data backup taken before migration
• [ ] Migration tested against production-scale data
• [ ] Stakeholders notified of timeline
• [ ] Monitoring dashboards ready for during/after
• [ ] On-call aware and available during migration
• [ ] Post-migration verification steps documented

Output

MIGRATION: [what's being migrated]
TYPE: [schema / api / dependency / platform]
RISK: [low / medium / high]
ESTIMATED DOWNTIME: [none / Xmin / Xhour]
ROLLBACK PLAN: [how to undo]
STEPS:
  1. [step] - [verification]
  2. [step] - [verification]
  ...
POST-MIGRATION:
  - [verification check]
  - [metric to monitor]

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.