# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.madrix.dev/br/solucao-de-problemas/banco-migrations-e-schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.