---
id: db-snapshot
agent: data-engineer
title: Criar snapshot do banco (ponto de rollback)
inputs: [label, escopo (schema | schema+dados)]
outputs: [snapshot rotulado, manifesto do snapshot (label, escopo, timestamp, ambiente)]
elicit: false
modes: [interactive, yolo]
---

# Criar snapshot do banco (ponto de rollback)

**Objetivo:** capturar um ponto de restauração rotulado do banco — para que toda mudança subsequente
seja reversível. Nenhuma migration acontece sem um snapshot antes.

**Pré-condições:**
- O ambiente-alvo está acessível e identificado (`db-env-check` ok).
- Há um label significativo (ex.: `pre-{migration-id}`, `baseline`). Snapshot sem label é snapshot que
  ninguém acha depois.

## Passos

1. **Defina o escopo:** só schema (estrutura/DDL) ou schema + dados. Para ponto de rollback de
   migration de estrutura, schema basta; quando dados podem ser afetados, incluo dados.
2. **Identifique o ambiente** (dev / staging / produção) e registre-o no manifesto — restaurar no
   ambiente errado é desastre, então o ambiente fica gravado.
3. **Gere o snapshot** (dump de schema e, se no escopo, de dados) com o label informado, em local
   versionado/seguro de snapshots.
4. **Verifique a integridade** do snapshot: o arquivo existe, não está vazio e é restaurável (checagem
   de consistência do dump).
5. **Escreva o manifesto:** label, escopo, ambiente, timestamp e a operação que ele protege. Segredos
   eventuais no dump são tratados com cuidado — nunca ecoo conteúdo sensível em log.
6. **Reporte o label do snapshot** para que `db-apply-migration` e `db-rollback` possam referenciá-lo.

## Critério de pronto (DoD)

- [ ] Snapshot gerado com o label e escopo corretos
- [ ] Integridade verificada (existe, não-vazio, restaurável)
- [ ] Manifesto registrado (label, escopo, ambiente, timestamp)
- [ ] Label reportado para uso por apply/rollback

## Falha / recuperação

- **A geração do snapshot falha** → HALT. Sem snapshot válido, **bloqueio** qualquer migration que
  dependia dele — reversibilidade é pré-condição.
- **O snapshot sai vazio ou corrompido** → descarto, recrio e só prossigo com um snapshot verificado.
- **Ambiente ambíguo** → paro e confirmo o ambiente antes de gerar; nunca assumo produção/dev por
  conta própria.