data-migration

Data Migration

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Felsefe

• Big-bang yasak. Faz faz (Parallel Change). Her aşama revert-edilebilir.
• Eski sistem son ana kadar yaşar. Cutover sonrası bile 30 gün hot.
• Backfill idempotent + restartable. 200 GB tek seferde değil, chunked + resume-from-checkpoint.
• Shadow read ile doğrulama: yeni sistem yanlışsa fark logla, response hâlâ eskiden.
• Rollback komutu yanıbaşında ve drill yapılmış — point of no return açıkça tanımlanmış.

Ne Zaman Kullanılır

• DB engine değişimi (Postgres → CockroachDB / Aurora; MySQL → Postgres)
• Schema major refactor (denormalize → normalize)
• Sharding (single-DB → multi-shard)
• Cloud → cloud (AWS RDS → GCP Cloud SQL)
• On-prem → cloud
• Legacy → modern (DB2 → Postgres)
• Data lake/warehouse migration (Redshift → BigQuery, Snowflake → Databricks)
• Service decomposition (monolith DB → microservice DB'leri)
• Compliance gerekliliği (PII anonymize, region taşıma — GDPR)
• Encryption-at-rest swap (yeni KMS key, data tabular re-encrypt)

Stratejiler

Stop-the-World (kabul edilmez prod'da)

1. Kapat sistem.
2. pg_dump | pg_restore.
3. Aç sistem.

Kullanım: dev/staging only, küçük lab. Prod'da downtime kabul edilemiyorsa yasak.

Lift-and-Shift

• AWS DMS / Azure DMS / GCP DMS managed servisler.
• CDC (Change Data Capture) tabanlı.
• Cutover penceresi kısa (saniyeler).
• Kısıtlama: schema benzer olmalı; major refactor yapılamaz.

Strangler Fig (Servis decomposition)

• Yeni servis eski'nin bir parçasını alır.
• API gateway / proxy yeni'ye yönlendirir.
• Eski sistem küçülür kontrollü.
• Genelde microservice extraction'da.

Expand-Contract (Parallel Change) — Plugin tercih

Phase 1: Expand
   ┌──────────────────────────────────────────┐
   │ Eski sistem yazıyor + okuyor (canonical)  │
   │ Yeni sistem yazıyor (shadow, no traffic)  │
   └──────────────────────────────────────────┘

Phase 2: Migrate
   ┌──────────────────────────────────────────┐
   │ Eski + Yeni dual-write (eşzamanlı)        │
   │ Backfill geçmiş veri (chunked)            │
   │ Shadow read: yeni'den oku, eski ile karş. │
   │ Diff sıfır → next phase                   │
   └──────────────────────────────────────────┘

Phase 3: Switch
   ┌──────────────────────────────────────────┐
   │ Read traffic yeni'ye (5/25/50/100 canary) │
   │ Write hâlâ dual                            │
   │ Eski hot replica olarak (read fallback)   │
   └──────────────────────────────────────────┘

Phase 4: Contract
   ┌──────────────────────────────────────────┐
   │ Write yeni only                            │
   │ Eski 30 gün hot (rollback ihtimali)        │
   │ Sonra cold archive → eventual delete       │
   └──────────────────────────────────────────┘

Workflow

1) Discovery + plan

• Scope: hangi tablolar / collection'lar / event topic'leri?
• Data volume: row count + storage GB.
• Throughput: peak insert/update/delete RPS.
• Constraints: foreign key, unique, trigger, materialized view.
• PII / compliance: GDPR / PCI / HIPAA scope tag.
• Cutover window: kabul edilen downtime (0 / dakikalar / saatler).
• Rollback point of no return: hangi phase'ten sonra geri dönüş yok?

2) Tooling seçimi

Kategori	Tool	Notlar
CDC managed	AWS DMS, Azure DMS, GCP Datastream	RDB → RDB; schema convert opsiyonel
CDC self-host	Debezium	Kafka Connect bazlı; flexible
ETL/ELT	dbt, Airbyte, Fivetran	Data warehouse migration
Postgres-spesifik	pg_logical_replication, pglogical	Postgres → Postgres
Bulk load	pg_dump/restore, COPY, pgloader	Initial load
Custom script	Python + asyncio + chunked SELECT	Karmaşık transform
Application-level	Servis kendi yazar	Schema farkı çok

3) Schema design

Expand phase:

• Yeni schema = eski + ek field'lar (compatible).
• Drop edilecek alanlar henüz drop edilmedi (rollback için).
• Yeni constraint deferred (initial load sırasında check kapalı, sonra enable).

-- Expand: yeni shape eklendi, eski hâlâ yaşıyor
ALTER TABLE users ADD COLUMN address_v2 JSONB;  -- yeni
-- address_v1 (string) hâlâ kullanılıyor

4) Dual-write

App katmanında her write iki sisteme gider:

async def create_order(order: Order) -> Order:
    # Eski sistem canonical (success kriteri)
    saved = await old_db.insert(order)

    # Yeni sistem shadow (failure tolere)
    try:
        await new_db.insert(order_to_new_shape(saved))
    except Exception as e:
        log.warn("dual_write_failed", error=str(e), order_id=saved.id)
        metrics.dual_write_fail.inc()
        # eski sistem zaten başardı → user bilgi alır

    return saved

Kurallar:

• Eski canonical, yeni shadow.
• Async / fire-and-forget olabilir (yeni latency'i etkilemesin).
• Idempotency key her iki tarafta aynı (dedup için).
• Failure metric: dual-write fail rate < %0.1 hedef.
• Compensating action plan (yeni'de eksik kalan satır → background reconcile).

5) Backfill (geçmiş veri)

async def backfill_chunk(start_id: int, end_id: int) -> int:
    """Chunked + idempotent + restartable."""
    rows = await old_db.fetch(
        "SELECT * FROM orders WHERE id >= $1 AND id < $2 ORDER BY id",
        start_id, end_id,
    )
    transformed = [order_to_new_shape(r) for r in rows]

    # UPSERT (idempotent — restart safe)
    await new_db.execute_many(
        "INSERT INTO orders_v2 (id, ...) VALUES ($1, ...) "
        "ON CONFLICT (id) DO UPDATE SET ... ",
        transformed,
    )

    # Checkpoint
    await save_checkpoint("orders_backfill", end_id)
    return len(rows)

Kurallar:

• Chunk size (ör. 1000 row) — DB'yi kilit'lemesin.
• Rate limit (örn. 100 chunk/dk) — prod load'a etkisi az.
• Resumable: checkpoint table'ı veya Redis key.
• Idempotent: UPSERT (ON CONFLICT DO UPDATE), yeniden çalıştırılırsa duplicate yok.
• Off-peak window: trafik düşük saatte (gece 02:00-06:00).
• Progress dashboard: Prometheus metric backfill_rows_total, ETA hesabı.
• Validation: backfill bitti → row count + checksum eski vs yeni.

6) Shadow read

App katmanında okuma eski'den ama paralel yeni'den de — fark logla:

async def get_order(order_id: int) -> Order:
    old_result = await old_db.get(order_id)

    # Shadow read: paralel, response'u etkilemiyor
    asyncio.create_task(_shadow_compare(order_id, old_result))

    return old_result   # canonical eski

async def _shadow_compare(order_id: int, old_result: Order) -> None:
    try:
        new_result = await new_db.get(order_id)
        if not orders_match(old_result, new_result):
            log.warn("shadow_mismatch", order_id=order_id,
                     diff=diff_orders(old_result, new_result))
            metrics.shadow_mismatch.inc()
    except Exception as e:
        log.warn("shadow_read_failed", error=str(e))

Mismatch < %0.01 → switch hazır.

7) Cutover

Read traffic switch (Phase 3):

• Feature flag read_from_new_db per-region/per-tenant.
• Canary: %5 → %25 → %50 → %100 (her step 24 saat sustained).
• Abort eşik: error rate > %0.5, latency > +%20.
• Rollback: feature flag toggle (saniyeler).

Write traffic switch (Phase 4'e geçiş):

• Eski'ye write durdur (dual-write off, yeni only).
• Eski 30 gün hot replica (rollback için).
• Cutover anında maintenance window opsiyonel (saniyeler):
  • Stop new writes.
  • Wait dual-write queue drain (Kafka lag = 0).
  • Switch flag.
  • Resume writes (yeni only).

8) Rollback

Phase	Rollback	Komut
Expand	Kolay — yeni schema kullanılmıyor; drop.	ALTER TABLE users DROP COLUMN address_v2;
Migrate (dual-write)	Kolay — yeni'yi kapat (feature flag). Veri eski'de canonical.	flag.disable("dual_write_new_db")
Switch (read)	Read flag toggle → eski'ye geri.	flag.disable("read_from_new_db")
Switch (write)	Point of no return yakın. 30 gün hot eski'den yeni'ye reverse-backfill yap.	reverse migration script
Contract	No rollback (eski silinmiş).	DR backup'tan restore.

Drill: phase 3'te 1 saatlik chaos drill — yeni DB'yi kapat, fallback eski → recovery süresi ölç.

9) Audit + monitoring

• Migration metrics:
  • backfill_rows_total{table} (counter)
  • dual_write_fail_total (counter)
  • shadow_mismatch_total (counter)
  • migration_lag_seconds (gauge)
  • cutover_phase (gauge: 0/1/2/3/4)
• Validation queries:
  • Row count: SELECT count(*) FROM old.orders vs SELECT count(*) FROM new.orders.
  • Checksum: MD5(json_agg(row)) GROUP BY chunk.
  • Sample diff: 1000 random row eski ↔ yeni karşılaştır.
• Audit log:
  • Cutover karar: kim onayladı, ne zaman.
  • Rollback drill: ne zaman, kaç dakika sürdü.
  • Compliance evidence: data retention, encryption swap.

10) Compliance / PII

• GDPR Art. 5 data minimization: migration sırasında PII anonymize fırsatı.
• Encryption-at-rest swap: KMS key rotate; tabular re-encrypt.
• Audit log: kim ne zaman erişti (migration script'i dahil).
• Right to erasure: migration'da silme listesi (deleted users) korumayı unutma.
• Cross-border transfer (GDPR Art. 44+): EU → US migration adequacy decision + SCC.

Checklist

• Strateji seçildi (Expand-Contract default; Lift-Shift uygunsa)
• Scope: tablo/collection/topic + row count + GB
• PII / compliance scope tag
• Tooling seçildi (DMS / Debezium / pgloader / custom)
• Phase plan: Expand → Migrate → Switch → Contract
• Dual-write: eski canonical, yeni shadow
• Backfill: chunked + idempotent + restartable + checkpoint + rate limit
• Shadow read: paralel, fark logla, mismatch < %0.01
• Cutover: canary read (5/25/50/100); maintenance window kısa
• Rollback: her phase için komut + drill yapıldı
• Point of no return açıkça tanımlandı
• Validation: row count + checksum + sample diff
• Audit log: cutover + rollback + compliance evidence
• Migration metric dashboard
• Maintenance window iletişimi (customer notify)

Antipattern

• Big-bang pg_dump | pg_restore prod'da — downtime saatler.
• Cutover öncesi shadow read yok — yeni sistem doğru emin değil.
• Backfill chunked değil — 200 GB tek seferde lock + lag.
• Backfill restartable değil — fail → baştan başla.
• Eski sistem hemen kapatılır — rollback imkansız.
• Drill yapılmamış rollback — kritik anda öğrenme.
• Dual-write success kriteri yeni — yeni fail → eski de fail görünür.
• Compensating action yok — dual-write fail'de yeni'de eksik satır kalıcı.
• Validation row count only — checksum ve sample yok; veri silently bozulabilir.
• Maintenance window customer'a duyurulmadı — destek storm.
• PII migration anonymize fırsatı kaçırıldı — yeni sistem aynı PII yükü.
• Encryption-at-rest swap deferred — compliance gap.
• Migration metric yok — progress + fail görünmez.

Örnek Agent Davranışı

User: /data-migration postgres-to-cockroach
Agent (migration-planner):
1. Scope: orders + payments + users 3 tablo, ~280M satır, 420 GB, peak 850 TPS.
2. Strateji: Expand-Contract (zero-downtime hedef; PCI scope korunmalı).
3. Tooling: pglogical + custom Python backfill (CockroachDB pgwire compatible).
4. Phase 1 (Expand, 1 hafta): yeni cluster + schema + sealed-secrets connection.
5. Phase 2 (Migrate, 3 hafta): dual-write app + backfill chunked 100 row/sn,
   shadow read ön validation.
6. Phase 3 (Switch read, 2 hafta canary): 5/25/50/100 region.
7. Phase 4 (Switch write + Contract, 1 hafta): write yeni only; eski 30 gün hot.
8. Validation: row count + MD5 checksum 1k chunk + 5k sample diff.
9. Rollback drill phase 3'te (chaos: yeni cluster kapat → eski fallback).
10. Compliance: KMS key swap (CockroachDB encryption); GDPR audit log.
11. Output: 47 day migration plan + 12 issue + maintenance window 2026-08-15
    customer notify.

Çıktı Formatı

# Data Migration: <source> → <target>

## Strateji
- Expand-Contract / Lift-Shift / Strangler

## Scope
- Tablo / row count / GB / RPS / constraint

## Phase Plan
| Phase | Süre | Aksiyon | Rollback |

## Backfill
- Tool, chunk size, rate, idempotent

## Validation
- Row count, checksum, sample diff

## Rollback
- Phase başına komut + drill

## Audit + Compliance
- KMS, GDPR, PCI, audit log

## Action Items
| P | Aksiyon | Sahip | Bitiş | Issue |