---
id: db-verify-order
agent: data-engineer
title: Lint da ordem do DDL de uma migration
inputs: [migration_path]
outputs: [veredito de ordem (OK/erros), lista de dependências fora de ordem]
elicit: false
modes: [interactive, yolo]
---

# Lint da ordem do DDL de uma migration

**Objetivo:** garantir que o DDL de uma migration está em ordem topológica — dependências criadas
antes de quem as usa — para que a aplicação não falhe no meio por referência a objeto inexistente.

**Pré-condições:**
- O arquivo de migration existe em `migration_path`. Se não existir, **pare** e reporte.
- A migration é DDL (cria/altera estruturas). Se for só DML/seed, esta task não se aplica — use
  `*dry-run` ou `*seed`.

## Passos

1. **Leia a migration inteira** e liste os objetos definidos: tabelas, tipos/enums, funções,
   sequences, índices, FKs, políticas RLS, triggers, views.
2. **Monte o grafo de dependências:** tipo/enum antes da coluna que o usa; tabela referenciada antes
   da FK; tabela antes do índice/política/trigger dela; função antes do trigger que a chama.
3. **Verifique a ordem de declaração contra o grafo.** Todo objeto deve aparecer DEPOIS de tudo que
   ele depende. Marque cada violação (linha X usa objeto definido só na linha Y > X).
4. **Cheque idempotência junto:** `IF NOT EXISTS`/`IF EXISTS` nas criações e drops, para o replay ser
   seguro. Ausência é débito a sinalizar.
5. **Detecte ciclos** (A depende de B que depende de A): exigem `ALTER TABLE ADD CONSTRAINT` separado
   após ambas as tabelas existirem.
6. **Emita o veredito:** OK (ordem topológica válida) ou ERROS (lista de objetos fora de ordem, com
   linha e dependência faltante), sem aplicar nada — esta é uma task de lint, não de execução.

## Critério de pronto (DoD)

- [ ] Todos os objetos do DDL inventariados e mapeados em dependências
- [ ] Cada dependência aparece antes de quem a usa — ou a violação foi reportada com linha
- [ ] Ciclos detectados e a correção (constraint separada) apontada
- [ ] Idempotência verificada (IF [NOT] EXISTS)
- [ ] Veredito emitido; nada aplicado no banco

## Falha / recuperação

- **Objeto fora de ordem** → veredito ERROS com a linha exata; devolvo ao autor da migration para
  reordenar antes do `*dry-run`/`*apply-migration`.
- **Ciclo de FK** → recomendo quebrar em `CREATE TABLE` (ambas) → `ALTER TABLE ADD CONSTRAINT`.
- **Migration ilegível/parcial** → **pare** e reporte; não dou veredito OK por arquivo incompleto.