Playbooks de migração

1) Classificação das migrações

Esquemas de base de dados: adição/alteração de colunas, índices, charding, mudança de tipo de chave.
Dados: backfill em massa/cleanup, normalização, retenção/arquivo.
Serviços e API: mudança de endpoint, versionização, refacção de contratos.
Filas/pneus: mudança de topics, alteração de chaves de partilha, formato de evento.
Infraestrutura: mudança para o novo cluster/K8s/nuvem/região, mudança de segredos/KMS.
Armazenamento e análise: mudança de motor (OLTP/OLAP), formato/particionamento de datasets.
Segurança/Complacência: Rotação de chaves, criptografia em voo, localização de dados geo.

2) Princípios de migração bem sucedida

1. Expand → Migrate → Contract. Primeiro expandimos o padrão/comportamento (compatível), depois transferimos dados/tráfego e depois removemos o antigo.
2. Shadow & Dual. Verificação instantânea (shadow read/write) e dupla gravação para validação.
3. Bandeiras fichas e botão vermelho. Desativação rápida, ativação passo a passo (persentil/tenentes/regiões).
4. Idempotidade e repetência. Os script e tarefas podem ser reiniciados sem efeitos colaterais.
5. Observabilidade antes de alterações. Dashboards/alertas com antecedência, marcadores de migração em logs/trailers.
6. A reversão foi documentada. Runbook revezamento é tão detalhado quanto o plano para frente.
7. Mini lotes e pausas. Migramos com pequenas porções, verificando SLI e invariantes de negócios.

3) Inventário e análise de dependência

Mapa do Consumidor: serviços, jobs, relatórios, parceiros externos, BI/ETL, webhooks.
Contratos e esquemas: API/eventos, compatibilidade backward/forward.
Acessíveis/segredos: quem lê/escreve onde estão os cajus/réplicas.
Invariantes de domínio: exclusividade, equilíbrio, idempotidade, 24 horas relatadas.
Volume/velocidade: tamanho de dados, RPS, janelas de pico, RPO/RTO.

4) Modelo canônico de playbook (esqueleto YAML)

yaml playbook: "migrate-orders-to-v2"
owner: "orders-team"
stakeholders: ["platform", "data", "security", "support"]
change_type: ["schema", "data", "api"]
risk_level: "high"
preconditions:
- "Dashboards ready: latency/error/lag"
- "Runbook rollback validated on stage"
- "Backups verified (restore tested)"
plan:
phase_1_prepare:
steps:
- "Add new nullable columns (expand)"
- "Deploy code with dual-write (flag off)"
- "Enable CDC stream to target"
phase_2_shadow:
steps:
- "Shadow-read v2, compare with v1 (1%)"
- "Fix discrepancies; iterate"
phase_3_dual_write:
steps:
- "Enable dual-write (10%→50%→100%)"
- "Start backfill in batches (size=10k, sleep=200ms)"
phase_4_cutover:
steps:
- "Switch reads to v2 by tenants (canary)"
- "Monitor SLI 30m; expand scope"
phase_5_contract:
steps:
- "Drop old indices/columns after T+14d"
- "Disable old topic/api; update docs/SDK"
guardrails:
abort_if:
- "error_rate > 0. 5% for 5m"
- "p95 > baseline1. 5 for 10m"
- "data_mismatch > 0. 01%"
rollback:
steps:
- "Flip flag: reads back to v1"
- "Stop backfill; continue dual-write to v1"
- "Replay missed events (DLQ→v1)"
validation:
checks:
- "Row counts match within epsilon"
- "Business invariants hold (balances, limits)"
comms:
- channel: "on-call-bridge"
- status_updates: "T-24h, T-1h, start, cutover, finish"
window: "low-traffic Sun 02:00–05:00 UTC"

5) Patternos de migração

5. 1 Circuitos de Base de Dados (RDBMS/NoSQL)

Adicione, não altere. Novas colunas/índices nullable → código lê o antigo e novo.
Reconstrução online. Use índices on-line/DDL paralelo.
Versões de serialização. Versionize payload nas colunas JSON/Proto/Avro.
Migração de chaves. A mudança de PK é uma tabela de correspondência temporária + trigger/CDC.

5. 2 Dados (backfill/cleanup)

CDC + backfill. Primeiro o fluxo de alterações (para ficar atrás), depois o backfill de lote.
Lotes e deadline. Batches pequenos com controle de laje, checkpoint e reativação.
Updates Idumpotentes. Upsert em chaves/versões naturais.

5. 3 Eventos e filas

'event_type@vN', os consórcios ignoram campos desconhecidos.
Mudança de topics. Publicação dupla, os consumidores leem de ambos antes da estabilização; depois «corte» do velho.
Partition key. Migrar a chave através de reedição com cartão de conformidade e idumpotência.

5. 4 Serviços e API

Blue/Green/Canary. Aquecimento do pulo, tráfego parcial, reversão rápida.
Bandeiras fichas. Por tenentes/regiões/porcentagem, a inclusão observada.
Contratos. Contratos CDC e testes de compatibilidade - antes de alternar.

5. 5 Regiões/Claudia

Geo-duplo. Os dados são registrados em duas regiões; leitura - por proximidade.
State transfer. Imagem + replicação; linha vermelha RPO, transbordamento DNS/Anycast.
Jurisdição. Consentimento/localização de dados, listas de «proibidos» para extração de conjuntos.

6) Fases de execução (detalhado)

1. Preparação

Dashboards, alertas, limites, bandeiras de fique, bacapes com teste de recuperação.

2. Shadow (verificação de shadow)

Espelhar as pesquisas/gravações para o novo sistema sem afetar os usuários. Comparando respostas/estados.

3. Dual-write / Dual-read

Escrevemos para ambos os lados. Leituras - Transferindo gradualmente para um novo sistema. Os logs de discrepância são analisados.

4. Backfill

Apanhamos dados históricos em lotes. Controlamos o CDC, vigiamos a carga de estorco/dinheiro.

5. Cutover (alternar)

Canarim por segmento (tenentes/regiões/juros). Apoiamos uma reversão rápida.

6. Contract (limpar)

Cortando caminhos antigos, removendo campos/índices/topics obsoletos após o «período de segurança».

7. Verificação e retro

Relatório, métricas, aulas, atualização de playbook/cheque-folhas.

7) Observabilidade e SLO durante a migração

SLI técnico: p50/p95/p99, error rate, retry/timeout, utilização, lag CDC, profundidade das filas.
Negócios SLI: sucesso de transações/conversões, invariantes (balanços, limites, duplicados).
Os rótulos especiais são 'migration _ id', 'phase', 'tenant', 'flag _ state'.
Alert-guardas: liminares e erros, «auto-pare» (abort) por SLO.
Painéis comparativos: v1 vs v2, «delta» em métricas-chave.

8) Retrocesso e cenários de emergência

Retrocesso lógico: bandeiras/rotação de tráfego para trás, congelamento de backfill.
Dados: «compensações» (Saga), réplicas de eventos, DLQ → sistema de origem.
Segredos/chaves: retorno para chave/certificado anterior (dual-key).
DNS/tráfego: «drift inverso» Anycast/ALB, TTL curto para a janela de migração.
Comunicações: canal pré-concordado e formato de estatais.

9) Segurança, privacidade, complacência

Minimizar os dados. Transferimos apenas os campos necessários; perfis de anonimato para cópias.
Criptografia. Criptografia «no fio» e «em paz», rotação KMS; Registro de operações com chaves.
Acessível no tempo. Papéis temporários para as migrações, seleção de direitos após a conclusão.
Marcas. Camuflar o PD em logs/trailers, limitar a exportação.

10) Gerenciamento de mudanças e comunicação

RACI: Quem afirma quem executa, quem é informado.
Período Freeze: Impede lançamentos não recorrentes na janela de migração.
Estados: T-24h, T-1h, partida, canarinho, cutover, meta, pós-mar.
Associados externos: janelas de compatibilidade, e-mails, caixa de areia de teste.

11) Modelos de runbook 'ov

11. 1 Backfill (pseudocode)

for batch in paginate(ids, size=10_000):
try:
rows = read_v1(batch)
upsert_v2 (rows) # idempotently mark_checkpoint (batch. end)
sleep(jitter_ms(100..300))
except Throttle:
sleep (5s) # backpressure respect except Fatal as e:
alert("backfill-failed", e, context=batch)
abort_if_needed()

11. 2 Proverka一致nosti (snapshot/amostra)

sample = random_ids(n=10_000, stratify=tenant,timestamp)
v1 = fetch_v1(sample); v2 = fetch_v2(sample)
assert schema_compatible(v2)
assert key_invariants_hold (v1, v2) # sum, statuses, versions mismatch_rate = diff (v1, v2). rate()
abort_if(mismatch_rate > 0. 0001)

11. 3 Alteração de leitura

flag. enable("read_from_v2", segment="tenants: cohort_A")
monitor(30m)
if SLO_ok(): expand_segment()
else: rollback_segment()

12) Anti-pattern

Big Bang em vez de expand-migrate-contracto.
O Backfill sem CDC → uma eterna busca e deriva.
Falta de idempotação → duplicações/dados sujos.
Passos manuais sem script → erros humanos.
Migração sem dashboards/guardas → voo cego.
Um retrocesso não confirmado não funciona quando necessário.
Ignorar os consumidores (BI/associados) → relatórios/integração «quebrados».

13) Folha de cheque do arquiteto

1. O objetivo, os limites, o tipo de migração e os invariantes do resultado são definidos?
2. O mapa dos consumidores e dos contratos foi feito, os testes de compatibilidade são verdes?
3. Estão preparados dashboards, alertas, marcas de 'migration _ id', SLO/guardas?
4. Implementado shadow e/ou dual-write, backfill é idepotente?
5. Há um rollback runbook praticado, verificações de recuperação do backap?
6. A janela/coordenação/comunicação está alinhada, freeze está ativado?
7. O plano passo a passo com canarinho e critérios de extensão/paragem está pronto?
8. Segurança/Complacência: chaves, acessíveis, saúde PII?
9. Documentação/SDK/speki são atualizados no mesmo ciclo de lançamento?
10. O pós-mar e a atualização do playbook estão programados?

Conclusão

Os playbooks de migração são práticas arquitetônicas de gerenciamento de risco: pequenos passos reversíveis, métricas transparentes, retrocesso pronto e disciplina «expand-migrate-contract». Seguindo os padrões descritos, você está migrando circuitos, dados, serviços e regiões sem interrupções ou surpresas, mantendo seus negócios invariantes e a confiança dos usuários.