---
id: db-seed
agent: data-engineer
title: Aplicar seed idempotente
inputs: [seed (path), story/spec de origem]
outputs: [dados de seed aplicados, registro da carga]
elicit: false
modes: [interactive, yolo]
---

# Aplicar seed idempotente

**Objetivo:** popular o banco com dados de referência/iniciais de forma idempotente — rodar de novo
não duplica nem quebra nada — sempre rastreando os dados a uma story/spec.

**Pré-condições:**
- O arquivo de seed existe e os dados rastreiam a um requisito/story (dados de referência, lookup,
  fixtures). Seed que inventa dados fora do escopo é **bloqueado** (Constituição Art. IV).
- O schema-alvo já está aplicado (as tabelas que o seed popula existem). Se não, **pare** e aplique a
  migration antes.

## Passos

1. **Confirme o ambiente-alvo** (dev / staging / produção). Seed de fixtures de teste **não** vai para
   produção; seed de dados de referência pode — confirmo qual é qual.
2. **Garanta a idempotência:** o seed usa `INSERT … ON CONFLICT DO NOTHING/UPDATE`, `MERGE` ou check
   por chave natural. Se o script não for idempotente, refatoro antes — rodar duas vezes tem que ser
   seguro.
3. **Aplique em transação** (`BEGIN … COMMIT`), respeitando a ordem de dependências (pais antes de
   filhos, FKs satisfeitas).
4. **Verifique a carga:** as linhas esperadas existem, sem duplicatas, com FKs válidas e constraints
   satisfeitas. Conto os registros e comparo com o esperado.
5. **Rode o seed uma segunda vez** num ambiente de teste para provar a idempotência: a contagem não
   muda. Essa é a prova, não a promessa.
6. **Registre a carga** (seed id, ambiente, linhas afetadas, timestamp) na trilha da story.

## Critério de pronto (DoD)

- [ ] Seed aplicado em transação, na ordem de dependências
- [ ] Idempotência provada (segunda execução não duplica)
- [ ] Contagem e integridade (FKs/constraints) verificadas
- [ ] Carga registrada na trilha da story; ambiente correto confirmado

## Falha / recuperação

- **O seed falha no meio** → `ROLLBACK` da transação; banco intacto. Reporto a linha/registro que
  causou e corrijo o seed.
- **A segunda execução duplica ou quebra** → o seed não é idempotente; HALT e refatoro antes de
  considerar pronto.
- **Seed mira produção com fixtures de teste** → bloqueio e reconfirmo o ambiente; dados de teste não
  contaminam produção.
- **Dados não rastreiam a story** → recuso a carga e escalo para alinhar escopo.