---
id: create-migration-plan
agent: data-engineer
title: Planejar a migração com estratégia de rollback
inputs: [schema, políticas RLS, índices, estado atual do banco]
outputs: [plano de migração, scripts up/down, docs/data/migration-plan.md]
elicit: false
modes: [interactive, yolo]
---

# Planejar a migração com estratégia de rollback

**Objetivo:** transformar as mudanças de schema/RLS/índices em um plano de migração seguro e
reversível — nada chega ao banco sem snapshot antes e script de rollback pronto.

**Pré-condições:**
- O DDL alvo existe (schema, RLS e/ou índices já desenhados). Sem alvo, não há plano.
- O estado atual do banco é conhecido (ou snapshotável). Se não dá para inspecionar o estado vigente,
  **pare** — migração sem baseline é salto no escuro.

## Passos

1. **Faça o diff** entre o estado atual e o DDL alvo: o que cria, altera, remove. Cada mudança no
   plano rastreia a uma story/spec — sem invenção de coluna ou tabela.
2. **Ordene as operações por dependência:** tipos/enums e tabelas referenciadas antes; FKs, índices e
   políticas RLS depois. Essa ordem é o que `db-verify-order` vai validar.
3. **Escreva o script `up` idempotente** (`IF NOT EXISTS`/`IF EXISTS`, `ADD COLUMN IF NOT EXISTS`):
   rodar duas vezes tem que ser seguro. Migration que só roda uma vez vai trair num replay.
4. **Escreva o script `down` (rollback) correspondente** para cada operação do `up`. Se eu não sei
   como desfazer uma mudança, eu não a coloco no plano — reversibilidade é pré-condição.
5. **Classifique operações destrutivas** (drop de coluna/tabela, mudança de tipo com perda): exigem
   snapshot obrigatório e, idealmente, migração em duas fases (expand/contract) para não derrubar a
   aplicação em execução.
6. **Defina a sequência de execução segura:** `db-snapshot` (baseline) → `db-dry-run` →
   `db-verify-order` → revisão de qualidade. CRÍTICO bloqueia a aplicação; ALTO exige mitigação ou
   rollback testado.
7. **Documente em `docs/data/migration-plan.md`:** diff, ordem, scripts up/down, operações
   destrutivas e a sequência de execução. A aplicação em si é a task `db-apply-migration` — aqui só
   planejo.

## Critério de pronto (DoD)

- [ ] Diff completo entre estado atual e alvo, cada mudança rastreável
- [ ] Operações ordenadas por dependência
- [ ] Script `up` idempotente
- [ ] Script `down` (rollback) cobrindo cada operação do `up`
- [ ] Operações destrutivas marcadas com snapshot obrigatório e estratégia de fase
- [ ] Sequência segura (snapshot → dry-run → verify-order → revisão) definida
- [ ] `docs/data/migration-plan.md` escrito

## Falha / recuperação

- **Uma operação não tem rollback claro** → não entra no plano até eu saber desfazê-la; reformulo a
  abordagem (ex.: expand/contract) para torná-la reversível.
- **Estado atual do banco inacessível** → paro; não planejo migração sem baseline confiável.
- **A migração exige push/deploy** → o plano é meu, mas a subida é do @devops; eu delego a aplicação
  em ambiente remoto ao @devops, sem nunca dar `git push` ou tocar em pipeline.