---
id: db-dry-run
agent: data-engineer
title: Testar uma migration sem commitar (dry-run)
inputs: [migration (path)]
outputs: [relatório de dry-run (sucesso/erro, objetos afetados, avisos)]
elicit: false
modes: [interactive, yolo]
---

# Testar uma migration sem commitar (dry-run)

**Objetivo:** rodar a migration dentro de uma transação que é sempre revertida no fim, para descobrir
erros, conflitos e efeitos colaterais **antes** de aplicar de verdade — sem alterar o banco.

**Pré-condições:**
- A migration existe no path informado.
- Há um ambiente de teste/dev acessível (`db-env-check` ok). Nunca rodo dry-run contra produção sem
  justificativa explícita — prefiro um clone/staging.

## Passos

1. **Abra uma transação** (`BEGIN`) no ambiente de teste. Tudo aqui dentro vai ser descartado no fim —
   por isso é seguro.
2. **Execute o DDL/DML da migration** dentro dessa transação, capturando cada erro com a linha/objeto
   que o causou.
3. **Colete os efeitos:** quais objetos seriam criados/alterados/removidos, quais constraints e FKs
   entram, se o baseline (`id`/`created_at`/`updated_at`) está presente nas tabelas novas.
4. **Sinalize riscos:** FK sem índice, coluna `NOT NULL` sem default em tabela com dados, operação que
   reescreve tabela grande (lock), tabela pública sem RLS. Aviso, não silencio.
5. **Reverta sempre** (`ROLLBACK`) ao final — com sucesso ou com erro. O dry-run **nunca** deixa
   resíduo no banco.
6. **Emita o relatório:** veredito (passa / falha), objetos afetados, avisos e a recomendação (seguir
   para `db-verify-order` + `db-apply-migration`, ou corrigir antes).

## Critério de pronto (DoD)

- [ ] Migration executada dentro de transação revertida (`ROLLBACK` garantido)
- [ ] Objetos afetados e avisos de risco listados
- [ ] Veredito claro: passa para aplicação ou volta para correção
- [ ] Nenhum resíduo deixado no banco

## Falha / recuperação

- **A migration falha no dry-run** → ótimo, foi exatamente pra isso. Reporto o erro com objeto/linha e
  devolvo para correção; **não** sigo para `db-apply-migration`.
- **O `ROLLBACK` não pôde ser garantido** (ex.: comando que faz commit implícito) → HALT, aviso que a
  migration não é dry-run-safe e exijo refatorá-la antes de qualquer aplicação real.
- **Sem ambiente de teste disponível** → escalo para o @devops provisionar; não rodo dry-run em
  produção como atalho.