---
id: migration-plan-tmpl
kind: template
agent: data-engineer
produces: docs/data-models/{versao}-migration-plan.md
---

# Migration Plan: {versão / descrição curta}

**Status:** Draft
**Banco-alvo:** {PostgreSQL / Supabase — ambiente}
**Schema-fonte:** {docs/data-models/{dominio}-schema.md — o design que esta migration materializa}
**Snapshot baseline:** {label do snapshot pré-migração — ponto de rollback}

## Objetivo

> O que esta migração muda e por quê. Cada mudança rastreia a uma story/spec/design (No Invention).

- {mudança 1 — rastro: story/spec/schema}
- {mudança 2 — rastro}

## Pré-condições

> O que precisa estar verdadeiro antes de aplicar. Reversibilidade é pré-condição.

- [ ] Snapshot `{label}` criado (`*snapshot {label}`)
- [ ] Rollback script pronto e testado (ver `## Rollback`)
- [ ] Ordem do DDL validada — dependências primeiro (`*verify-order {path}`)
- [ ] Dry-run executado sem erro (`*dry-run {path}`)
- [ ] Variáveis de ambiente do banco validadas (`*env-check`)
- [ ] {pré-condição específica desta migração}

## Mudanças (DDL, em ordem de dependência)

> Tabelas-pai antes de filhas; tipos/enums antes de colunas que os usam. Tudo idempotente (`IF NOT EXISTS` / `IF EXISTS`) — rodar de novo é seguro.

### Passo {n}: {descrição}

```sql
-- forward
{DDL idempotente}
```

**Impacto:** {tabelas afetadas, lock esperado, downtime?}
**Dados:** {migração/backfill de dados envolvido? volume?}

## Estratégia de Aplicação

| Item | Decisão |
|---|---|
| Transação | {tudo em uma transação? ou por passo?} |
| Janela | {online / janela de manutenção — por quê} |
| Lock esperado | {ACCESS EXCLUSIVE em {tabela}? duração estimada} |
| Backfill | {síncrono no DDL / batch separado / N/A} |
| Idempotência | {como rodar duas vezes não quebra} |

## Rollback

> Se eu não sei como desfazer, eu não aplico. Cada passo forward tem o seu reverso.

```sql
-- rollback (ordem inversa)
{DDL de reversão idempotente}
```

**Restauração de snapshot:** `*rollback {label}` — quando o rollback script não basta.
**Ponto de não-retorno:** {se houver — ex.: DROP de coluna com dados; o que se perde}

## Validação Pós-Migração

> Smoke-test antes de declarar pronto.

- [ ] Schema aplicado bate com o design (`*smoke-test {versao}`)
- [ ] Contagens de linha preservadas onde esperado
- [ ] Constraints/FKs ativas e válidas
- [ ] RLS aplicada nas tabelas que exigem (`*test-as-user`)
- [ ] Queries quentes sem regressão de performance (`*analyze-performance`)
- [ ] {validação específica desta migração}

## Riscos

| Risco | Severidade | Mitigação |
|---|---|---|
| {risco} | {CRÍTICO/ALTO/MÉDIO/BAIXO} | {como mitigo / rollback} |

> CRÍTICO bloqueia a aplicação; ALTO exige mitigação ou rollback script comprovado.

## Change Log

| Data | Mudança | Autor |
|---|---|---|
| {data} | {o quê} | @data-engineer |