---
id: db-run-sql
agent: data-engineer
title: Executar SQL bruto em transação
inputs: [arquivo .sql, objetivo/story que justifica a execução]
outputs: [resultado da execução, snapshot prévio, log da transação]
elicit: false
modes: [interactive, yolo]
---

# Executar SQL bruto em transação

**Objetivo:** rodar um arquivo SQL contra o banco dentro de uma transação reversível, com snapshot
antes e rollback garantido se algo falhar — sem inventar SQL fora do que o arquivo e a story pedem.

**Pré-condições:**
- O arquivo `.sql` existe, é legível e rastreia a uma story/spec/objetivo. Se não rastreia, **pare**
  e elicito o porquê — não executo SQL órfão (Constituição Art. IV).
- As variáveis de ambiente do banco estão válidas (rode `db-env-check` antes se houver dúvida). Sem
  conexão verificada, **pare**.
- Eu li o conteúdo do SQL inteiro. Se ele contém DDL destrutivo (`DROP`, `TRUNCATE`, `DELETE` sem
  `WHERE`), confirmo o alvo e o escopo antes de prosseguir.

## Passos

1. **Leia o arquivo `.sql` por completo** e classifique a operação: leitura pura, DML, ou DDL que
   altera schema. DDL/DML destrutivo exige snapshot obrigatório no passo 2; leitura pura pode pular.
2. **Tire um snapshot** do estado relevante (`db-snapshot {label}`) como ponto de rollback, sempre que
   o SQL escreve ou altera schema. Sem snapshot, eu não aplico mudança que escreve.
3. **Abra uma transação explícita** (`BEGIN`) e execute o conteúdo do arquivo dentro dela. Nada de
   autocommit por statement em mudança de schema/dados — ou tudo entra, ou nada entra.
4. **Verifique o resultado antes do commit:** contagem de linhas afetadas, ausência de erro, e
   coerência com o que a story esperava. Se algo destoa do esperado, faço `ROLLBACK` e reporto.
5. **Commit** (`COMMIT`) só quando o resultado bate com o esperado. Em qualquer erro durante a
   execução, `ROLLBACK` automático — a transação garante que rodar de novo é seguro.
6. **Redija segredos** em qualquer eco de resultado ou log (senhas, tokens nunca aparecem inteiros).
7. **Registre** o que rodou: arquivo, label do snapshot, linhas afetadas e status final, na story ou
   no log da operação — é o rastro de auditoria.
8. **Smoke-test rápido** quando o SQL alterou schema/dados críticos: uma query de verificação que
   prova que o estado pós-execução está consistente.

## Critério de pronto (DoD)

- [ ] SQL rastreia a uma story/spec; nada órfão foi executado
- [ ] Snapshot prévio criado para qualquer operação que escreve ou altera schema
- [ ] Execução ocorreu dentro de transação explícita (`BEGIN`…`COMMIT`/`ROLLBACK`)
- [ ] Resultado verificado contra o esperado antes do commit
- [ ] Segredos redigidos em logs e ecos
- [ ] Operação registrada (arquivo, snapshot, linhas afetadas, status)

## Falha / recuperação

- **Erro durante a execução** → `ROLLBACK` automático da transação; reporto o erro e o estado
  preservado pelo snapshot. Nada parcial fica no banco.
- **Resultado destoa do esperado** → `ROLLBACK`, registro a divergência e devolvo à origem (story/
  @architect) em vez de forçar o commit.
- **Snapshot falhou** → **HALT**. Sem ponto de rollback eu não escrevo no banco.
- **Conexão indisponível ou env inválido** → paro e rodo/encaminho `db-env-check`; não tento conexão
  às cegas.
- **O SQL exige subir algo (push, release)** → eu não faço; delego ao @devops. Eu só executo contra o
  banco, localmente.