---
id: setup-database
agent: data-engineer
title: Configurar o projeto de banco de dados
inputs: [tipo de banco (supabase/postgresql/mysql…), variáveis de ambiente]
outputs: [estrutura do projeto de banco, .env validado, conexão verificada]
elicit: true
modes: [interactive]
---

# Configurar o projeto de banco de dados

**Objetivo:** deixar o projeto de banco pronto para receber schema e migrations — estrutura de
diretórios, ambiente validado e conexão verificada — com segurança desde a configuração.

**Pré-condições:**
- O tipo de banco está definido ou será elicitado (PostgreSQL/Supabase por padrão). A escolha de
  tecnologia, se ainda em aberto, é do @architect — eu configuro o que foi decidido.
- Há acesso às credenciais de conexão (ou ao cofre/`.env` onde elas vivem).

## Passos

1. **Confirme o tipo de banco e o ambiente alvo** (PONTO DE ELICITAÇÃO — exige confirmação do
   usuário): qual engine? qual ambiente (local/staging/produção)? Eu não presumo produção nem
   sobrescrevo ambiente sem o usuário dizer.
2. **Crie a estrutura do projeto de banco** sob `docs/data-models/` (config) e `docs/data/` (docs):
   diretórios para migrations, seeds, snapshots e políticas. Estrutura previsível é o que as tasks
   `db-*` esperam.
3. **Valide as variáveis de ambiente** (equivalente a `db-env-check`): host, porta, database, user,
   credencial, modo SSL. Em produção, exijo Pooler com `sslmode=require`. Variável faltando = pare.
4. **Verifique a conexão** com um teste leve (ping/`SELECT 1`). Sem conexão verificada, não declaro o
   setup pronto.
5. **Garanta o tratamento de segredo:** confirme que credenciais estão em `.env`/cofre e nunca em
   código versionado; redijo qualquer segredo em logs. Service role, se presente, fica marcado como
   sensível.
6. **Crie um snapshot baseline inicial** (via `db-snapshot`) se já houver schema existente — ponto de
   rollback antes de qualquer trabalho futuro.
7. **Documente o setup** em `docs/data/setup.md`: tipo de banco, ambiente, estrutura criada e
   pré-requisitos para as próximas tasks (`create-schema`, `create-migration-plan`).

## Critério de pronto (DoD)

- [ ] Tipo de banco e ambiente confirmados pelo usuário no ponto de elicitação
- [ ] Estrutura de diretórios criada (migrations, seeds, snapshots, políticas)
- [ ] Variáveis de ambiente validadas; produção com Pooler + `sslmode=require`
- [ ] Conexão verificada (`SELECT 1` ou equivalente)
- [ ] Segredos fora do versionamento e redigidos em logs
- [ ] Snapshot baseline criado se havia schema preexistente
- [ ] `docs/data/setup.md` escrito

## Falha / recuperação

- **Variável de ambiente ou credencial faltando** → paro e reporto exatamente qual; não invento valor
  nem assumo default de produção.
- **Conexão falha** → não declaro pronto; reporto o erro (com segredo redigido) e escalo a infra ao
  @devops se for caso de rede/provisionamento.
- **Provisionamento de infra/MCP/secrets remotos** → delego ao @devops; configuração de
  infraestrutura e MCP é exclusiva dele, eu não toco.
- **Escolha de engine ainda em aberto** → escalo ao @architect antes de configurar; não decido
  tecnologia de sistema.