Skip to main content
skill CX Codex

migration-planner — Claude Code skill: phased migration plan with rollback

migration-planner turns a database or platform move into ordered phases with feature flags, dual writes, backfill and checks, plus a way back from each step.

MIT 279 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill migration-planner -a claude-code
Open on GitHub

What migration-planner does

The skill produces a migration plan as a document, for a database, a service or a whole platform. It starts by picking a pattern: a flag-gated rollout that ramps traffic up in steps, dual writes that keep both stores in sync, or blue-green with traffic moved between two environments.

Every phase in the template asks for a goal, numbered steps, sample code, validation and a rollback line. Around them sit sections on data integrity (row counts, random samples, checksums), risks with mitigations, a stakeholder update schedule, and testing split into pre-migration and during. The worked example moves a user database from MySQL to PostgreSQL.

Late phases carry the real cost: decommission is marked as a point of no return with no rollback, since the old cluster is shut down. Phase order is the safety net. Validation at each step is what lets you reach that point with matching data.

What it helps with

  • lay out a MySQL to PostgreSQL move as phases with checks
  • ramp a new code path from 1% of traffic up to 100%
  • compare two stores by row counts, samples and checksums
  • set up dual writes and backfill historical rows in batches
  • know which phase still allows a rollback and which one does not

Example prompts for the agent

  • Plan a move of the users database from MySQL to PostgreSQL, with validation and a rollback for each phase.
  • Write the dual-write stage: both databases take writes, then backfill history in batches of 1000 rows.
  • Add a risks section and a checksum comparison between the old and new users tables.

How to install migration-planner

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill migration-planner -a claude-code

2Manually: put the files in place

~/.claude/skills/migration-planner/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/migration-planner/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about migration-planner

How do I install migration-planner in Claude Code?

Run npx skills add patricio0312rev/skills --skill migration-planner -a claude-code. The skill lands at ~/.claude/skills/migration-planner/SKILL.md.

What does migration-planner do?

It drafts a migration plan with validation and a rollback for every phase, built on feature flags, dual writes or blue-green deployment.

How is dual write different from blue-green?

Dual write updates the old and new store at the same time, so history can be backfilled afterwards. Blue-green runs two environments and switches traffic between them, and switching back is the rollback.

Source text

SKILL.md · MIT
---
name: migration-planner
description: Builds phased data and system migrations using feature flags, dual writes, backfills, and validation. Includes rollback plans and risk mitigation. Use for "data migration", "system migration", "database migration", or "platform migration".
---

# Migration Planner

Execute safe, zero-downtime migrations with validation and rollback plans.

## Migration Patterns

### 1. Feature Flag Migration (Safest)

```
Phase 1: Deploy new code (disabled)
Phase 2: Enable for 1% traffic
Phase 3: Ramp to 10%, 50%, 100%
Phase 4: Remove old code
```

### 2. Dual Write Migration

```
Phase 1: Write to both old and new
Phase 2: Backfill old → new
Phase 3: Read from new (write both)
Phase 4: Stop writing to old
Phase 5: Decommission old
```

### 3. Blue-Green Deployment

```
Blue (current) → Green (new)
Switch traffic: Blue → Green
Rollback available: Green → Blue
```

## Complete Migration Plan Template

````markdown
# Migration Plan: MySQL → PostgreSQL

## Overview

**What:** Migrate user database from MySQL to PostgreSQL
**Why:** Better JSON support, improved performance
**When:** Q1 2024
**Owner:** Database Team
**Risk Level:** HIGH

## Current State

- MySQL 8.0
- 500GB data
- 100K users
- 1000 writes/min
- 10,000 reads/min

## Target State

- PostgreSQL 15
- Same data model
- No downtime
- Data validation 100% match

## Phases

### Phase 1: Dual Write (Week 1-2)

**Goal:** Write to both databases

**Steps:**

1. Deploy PostgreSQL cluster
2. Create schema in PostgreSQL
3. Deploy dual-write code
4. Enable dual writes (MySQL primary, PostgreSQL secondary)

**Code:**

```typescript
async function createUser(data: CreateUserDto) {
  // Write to MySQL (primary)
  const mysqlUser = await mysql.users.create(data);

  // Write to PostgreSQL (secondary, fire and forget)
  postgres.users.create(data).catch((err) => {
    logger.error("PostgreSQL write failed", err);
  });

  return mysqlUser; // Still trust MySQL
}
```
````

**Validation:**

- Monitor PostgreSQL write success rate
- Compare row counts daily
- Alert if drift >0.1%

**Rollback:** Disable PostgreSQL writes

### Phase 2: Backfill (Week 3-4)

**Goal:** Copy historical data

**Steps:**

1. Take MySQL snapshot
2. Run backfill script in batches
3. Validate data integrity
4. Resume from failure automatically

**Script:**

```python
def backfill():
    last_id = get_last_migrated_id()
    batch_size = 1000

    while True:
        users = mysql.query(
            "SELECT * FROM users WHERE id > %s LIMIT %s",
            [last_id, batch_size]
        )

        if not users:
            break

        postgres.bulk_insert(users)
        last_id = users[-1]['id']
        save_checkpoint(last_id)

        time.sleep(0.1)  # Rate limit
```

**Validation:**

- Row count match
- Random sample comparison (1000 rows)
- Checksum comparison

**Rollback:** Delete PostgreSQL data

### Phase 3: Dual Read (Week 5)

**Goal:** Validate PostgreSQL reads

**Steps:**

1. Deploy shadow read code
2. Read from both (MySQL primary)
3. Compare results
4. Log mismatches

**Code:**

```typescript
async function getUser(id: string) {
  const mysqlUser = await mysql.users.findById(id);

  // Shadow read from PostgreSQL
  postgres.users.findById(id).then((pgUser) => {
    if (!deepEqual(mysqlUser, pgUser)) {
      logger.warn("Data mismatch", { id, mysqlUser, pgUser });
      metrics.increment("migration.mismatch");
    }
  });

  return mysqlUser; // Still trust MySQL
}
```

**Validation:**

- Mismatch rate <0.01%
- PostgreSQL query performance acceptable

**Rollback:** Remove shadow reads

### Phase 4: Flip Read Traffic (Week 6)

**Goal:** Read from PostgreSQL

**Steps:**

1. Feature flag: read from PostgreSQL (1% traffic)
2. Monitor errors, latency
3. Ramp: 1% → 10% → 50% → 100%
4. Still writing to both

**Code:**

```typescript
async function getUser(id: string) {
  if (featureFlags.readFromPostgres) {
    return postgres.users.findById(id);
  }
  return mysql.users.findById(id);
}
```

**Validation:**

- Error rate unchanged
- Latency p95 <500ms
- No user complaints

**Rollback:** Flip feature flag off

### Phase 5: Stop MySQL Writes (Week 7)

**Goal:** PostgreSQL is now primary

**Steps:**

1. Stop writing to MySQL
2. Keep MySQL running (read-only)
3. Monitor for issues

**Code:**

```typescript
async function createUser(data: CreateUserDto) {
  return postgres.users.create(data);
  // No longer writing to MySQL
}
```

**Validation:**

- All operations working
- MySQL not receiving writes

**Rollback:** Re-enable MySQL writes

### Phase 6: Decommission (Week 8)

**Goal:** Remove MySQL

**Steps:**

1. Archive MySQL data
2. Shutdown MySQL cluster
3. Remove MySQL client code

**Rollback:** Not available (point of no return)

## Validation Strategy

### Data Integrity Checks

```python
def validate_migration():
    # Row counts
    mysql_count = mysql.query("SELECT COUNT(*) FROM users")[0]
    pg_count = postgres.query("SELECT COUNT(*) FROM users")[0]
    assert mysql_count == pg_count

    # Random sampling
    sample = mysql.query("SELECT * FROM users ORDER BY RAND() LIMIT 1000")
    for row in sample:
        pg_row = postgres.query("SELECT * FROM users WHERE id = %s", [row['id']])
        assert row == pg_row

    # Checksums
    mysql_checksum = mysql.query("SELECT MD5(GROUP_CONCAT(id, email)) FROM users")
    pg_checksum = postgres.query("SELECT MD5(STRING_AGG(id::text || email, '')) FROM users")
    assert mysql_checksum == pg_checksum
```

## Rollback Plans

### Phase 1-3 Rollback (Easy)

- Disable PostgreSQL writes
- No impact to users
- Data in MySQL still valid

### Phase 4 Rollback (Medium)

- Flip feature flag
- Route reads back to MySQL
- Minor user impact (seconds)

### Phase 5+ Rollback (Hard)

- Must re-enable MySQL writes
- Potential data loss (writes since phase 5)
- Requires dual-write resumption

## Risk Mitigation

### Risk 1: Data Loss

**Mitigation:**

- Dual writes until validated
- Transaction logs captured
- Continuous backups

### Risk 2: Performance Degradation

**Mitigation:**

- Load test PostgreSQL
- Query optimization
- Connection pooling

### Risk 3: Schema Differences

**Mitigation:**

- Schema validation script
- Test migrations in staging
- Document data type differences

## Communication Plan

### Stakeholder Updates

```markdown
**Week 0:** Migration announced
**Week 2:** Phase 1 complete (dual writes)
**Week 4:** Backfill complete
**Week 6:** Traffic shifted to PostgreSQL
**Week 8:** Migration complete
```

### Status Dashboard

- Current phase
- Data sync status (%)
- Validation results
- Error rates

## Testing Plan

### Pre-Migration Testing

1. Test in development
2. Full migration in staging
3. Load test PostgreSQL
4. Validate rollback procedures

### During Migration

1. Continuous monitoring
2. Automated validation
3. Manual spot checks
4. User acceptance testing

## Best Practices

1. **Small batches**: Migrate incrementally
2. **Dual write**: Keep both systems synchronized
3. **Feature flags**: Control rollout
4. **Validate continuously**: Don't trust, verify
5. **Rollback ready**: Plan for worst case
6. **Monitor closely**: Track metrics
7. **Communicate often**: Keep stakeholders informed

## Output Checklist

- [ ] Migration phases defined (5-7 phases)
- [ ] Dual write implementation
- [ ] Backfill script ready
- [ ] Validation strategy
- [ ] Feature flags configured
- [ ] Rollback plans per phase
- [ ] Risk mitigation strategies
- [ ] Communication plan
- [ ] Monitoring dashboard
- [ ] Testing checklist

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Data and databases →

From the same set148

The whole set →
pii-redaction-logging-policy-builder pii-redaction-logging-policy-builder sets up redaction rules and a logging policy to keep sensitive user data out of logs. Replaces emails, phone numbers, and payment cards with safe placeholders. CX Codex +1 283installs flaky-test-detective The flaky-test-detective skill traces intermittent test failures to timing, state, random data, or network calls. Use it when a test passes and fails across runs. CX Codex +1 283installs monorepo-setup monorepo-setup lays out a Turborepo and pnpm monorepo: apps, shared packages, TypeScript and ESLint configs, and a build pipeline. CX Codex +1 283installs typescript-strict-migrator typescript-strict-migrator moves a TypeScript codebase to strict mode one compiler flag at a time: audit the errors, then turn on noImplicitAny, strictNullChecks and the rest. Handy when strict: true throws too much at once. CX Codex +1 280installs code-formatter-installer code-formatter-installer installs Prettier, ESLint, EditorConfig and git hooks, then wires them into CI so the whole team formats code the same way. CX Codex +1 278installs caching-strategist caching-strategist turns a vague “add caching” request into named layers, key layouts, TTL values and invalidation rules, with TypeScript samples for Redis and CDN. CX Codex +1 278installs rest-to-graphql-migrator rest-to-graphql-migrator — a skill that walks a REST API over to GraphQL one endpoint at a time, wrapping existing routes instead of rebuilding the backend. CX Codex +1 277installs insomnia-collection-generator insomnia-collection-generator scans Express, Fastify, and Next.js routes to generate an Insomnia v4 collection export file with organized workspaces, folders, and environments. CX Codex +1 277installs

Project sponsors

Companies that keep this analytics open