К основному содержанию
скилл CX Codex

migration-planner — скилл для Claude Code: фазы миграции и откат

Скилл migration-planner помогает спланировать переезд базы или сервиса: раскатка за фича-флагом, двойная запись, бэкфилл истории и сверка данных на каждом шаге.

MIT 279 установок ★ 64 обновлён 2026-01-12

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add patricio0312rev/skills --skill migration-planner -a claude-code
Открыть на GitHub

Что делает migration-planner

Скилл пишет документ-план миграции: базы, сервиса или целой платформы. Сначала выбирается схема — раскатка за фича-флагом (1%, 10%, 50%, 100% трафика), двойная запись в старую и новую базу или blue-green с переключением трафика между двумя окружениями. Дальше план разбивается на фазы с шагами и проверками.

В каждой фазе шаблон просит цель, пронумерованные шаги, кусок кода, проверку и строку отката. Отдельные разделы — стратегия сверки данных (счётчики строк, случайная выборка, контрольные суммы), риски с мерами против них, план коммуникации со стейкхолдерами и тестирование до и во время переезда. Пример в шаблоне разобран на переезде пользовательской базы с MySQL на PostgreSQL.

Последняя фаза помечена как точка невозврата: откат там недоступен, потому что старую базу уже выключили. Поэтому порядок фаз и есть основная защита, а проверки на каждом шаге нужны, чтобы дойти до этой точки с совпадающими данными.

Какие задачи решает

  • расписать переезд с MySQL на PostgreSQL по фазам с проверками
  • раскатать новую ветку кода с 1% трафика до 100%
  • сверить две базы по счётчикам строк, выборке и контрольным суммам
  • настроить двойную запись и бэкфилл истории пачками
  • понять, на каком этапе откат ещё бесплатный, а на каком данные уже не вернуть

Примеры запросов агенту

  • Составь план миграции базы users с MySQL на PostgreSQL: фазы, проверки данных и откат для каждой.
  • Распиши этап двойной записи: пишем в обе базы, потом доливаем историю бэкфиллом пачками по 1000 строк.
  • Добавь в план раздел рисков и сверку контрольных сумм между старой и новой таблицей users.

Как установить migration-planner

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/migration-planner/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о migration-planner

Как установить migration-planner в Claude Code?

Выполните npx skills add patricio0312rev/skills --skill migration-planner -a claude-code. Скилл появится по пути ~/.claude/skills/migration-planner/SKILL.md.

Что делает migration-planner?

Собирает пошаговый план миграции с проверками и откатом на каждой фазе. Опирается на три схемы: фича-флаг, двойную запись и blue-green.

Чем двойная запись отличается от blue-green?

При двойной записи обе базы обновляются одновременно, поэтому историю можно долить бэкфиллом. Blue-green держит два окружения и переключает трафик между ними, откат — обратное переключение.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Данные и базы» →
migration JuliusBrussee Скилл migration задаёт правила безопасных миграций схем, данных и API с обязательным откатом. Пригодится при изменениях, где нельзя терять данные или ломать совместимость. CX Codex +1 127 700установок migration-architect Alireza Rezvani Скилл migration-architect для Claude Code планирует миграции баз данных, сервисов и инфраструктуры с проверкой совместимости и сценариями отката. CX Codex +1 632установок database-migration-management aj-geddes Скилл database-migration-management помогает планировать миграции схем, откаты изменений и трансформацию данных в PostgreSQL и MySQL. Пригодится при версионировании таблиц и создании индексов без блокировок. CX Codex +1 505установок deprecation-and-migration addyosmani Скилл deprecation-and-migration для Claude Code помогает выводить из эксплуатации старые системы и переносить пользователей на замену. Он подключается при миграции API, функций или схемы базы данных. CX Codex +1 73 100установок reviewing-oracle-to-postgres-migration официальный github Скилл reviewing-oracle-to-postgres-migration проверяет риски миграции с Oracle на PostgreSQL и помогает сверить миграционные артефакты с интеграционными тестами. CX Codex +1 1 800установок django-safe-migration vintasoftware Скилл django-safe-migration помогает писать и проверять миграции Django для PostgreSQL с учётом блокировок и выкладки без остановки приложения. Пригодится перед изменением схемы или релизом. CX Codex +1 822установок

Из того же набора148

Весь набор →
pii-redaction-logging-policy-builder Скилл pii-redaction-logging-policy-builder помогает настроить маскирование персональных данных в логах и составить политику логирования под GDPR. Заменяет email, телефоны и номера карт на плейсхолдеры. CX Codex +1 283установок flaky-test-detective Скилл flaky-test-detective для Claude Code ищет причины нестабильных тестов и предлагает способы их исправить. Разбирает сбои, которые возникают не при каждом запуске. CX Codex +1 283установок monorepo-setup Скилл monorepo-setup разворачивает каркас монорепозитория на Turborepo и pnpm: приложения, общие пакеты, конфиги TypeScript и ESLint, пайплайн сборки. CX Codex +1 283установок typescript-strict-migrator Скилл typescript-strict-migrator для Claude Code переводит TypeScript-проект на strict по одному флагу после аудита ошибок. Миграция начинается с noImplicitAny, затем включает strictNullChecks и остальные флаги. CX Codex +1 280установок code-formatter-installer Скилл code-formatter-installer ставит Prettier, ESLint, EditorConfig и git-хуки в проект и доводит настройку до CI, чтобы команда не спорила о форматировании. CX Codex +1 278установок caching-strategist Скилл caching-strategist для Claude Code раскладывает кеширование по слоям и выдаёт готовые ключи, TTL, правила сброса и защиту от stampede. Превращает задачу «добавь кеш» в рабочий код. CX Codex +1 278установок rest-to-graphql-migrator Скилл rest-to-graphql-migrator проводит пошаговую миграцию REST API на GraphQL: описывает эндпоинты, строит схему, оборачивает существующие ручки в data source и переносит их по одной. CX Codex +1 277установок insomnia-collection-generator Скилл insomnia-collection-generator сканирует эндпоинты в коде API на Express, Next.js или Fastify и собирает готовый файл экспорта рабочей области для Insomnia в формате v4. CX Codex +1 277установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой