# Banco, migrations e schema

### Quando usar

* Migration falha no deploy.
* App sobe, mas dá erro de tabela/coluna inexistente.
* Erros de conexão com banco.

### Checklist rápido (2 min)

1. Confirme em qual ambiente o erro ocorre.
2. Verifique a migration mais recente aplicada.
3. Veja se há divergência entre schema esperado e schema real.

### Diagnóstico

#### 1) Conexão

* Credenciais/URL corretas?
* Rede/VPC liberada (se aplicável)?

#### 2) Ordem e idempotência de migrations

* Migração depende de outra que não rodou?
* Migração roda duas vezes e quebra?

#### 3) Dados existentes

* Alteração de coluna com dados antigos costuma quebrar.
* Constraints (NOT NULL / FK) exigem backfill.

### Como resolver (padrões)

* **Erro de coluna/tabela**: revisar a última migration e o schema.
* **Constraint falhou**: fazer backfill antes de aplicar constraint.
* **Conexão**: validar secrets e permissões de rede.

### Quando escalar

* Migration quebra repetidamente no pipeline.
* Corrupção/dados inconsistentes.
* Erro só em Prod e não reproduz em Staging.

Antes de escalar, junte estas evidências. Isso reduz muito o ping-pong.

* Projeto e ambiente (Dev/Staging/Prod).
* Horário do erro (com timezone).
* Passos para reproduzir (curto e determinístico).
* Mensagem de erro completa (sem prints cortados).
* Screenshot da tela (se aplicável).
* Console do browser (erros e warnings relevantes).
* Aba **Network** (request que falhou + status + payload, se não houver dados sensíveis).

{% hint style="info" %}
Se existir um `requestId`, `traceId` ou link de execução, inclua também.
{% endhint %}