EXPLAIN Review Skill
Checklist de crítica de plano para PRs de equipes de aplicativos em PostgreSQL 18.4 - agentes de fluxo de trabalho SKILL.md estruturados e humanos usam para aceitar ou rejeitar alterações de consulta com evidências EXPLAIN.
//
Busque em todas as páginas da documentação
Checklist de crítica de plano para PRs de equipes de aplicativos em PostgreSQL 18.4 - agentes de fluxo de trabalho SKILL.md estruturados e humanos usam para aceitar ou rejeitar alterações de consulta com evidências EXPLAIN.
## EXPLAIN Review Skill - Checklist rápido
- [ ] EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) anexado
- [ ] Executa em staging com estatísticas em escala de produção (ANALYZE recente)
- [ ] Sem Seq Scan inesperado em tabelas grandes
- [ ] Estimativas de linha dentro de 10x do real (Linhas de Planejamento vs. Reais)
- [ ] Sem Sort em grandes conjuntos de linhas sem suporte de índice LIMIT
- [ ] Contagem de leitura de buffer justificada pela frequência da consultaEXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total
FROM orders o
WHERE o.tenant_id = $1 AND o.status = 'open'
ORDER BY o.created_at DESC
LIMIT 50;Quando invocar esta skill:
PR de Entrada: Queryset Django adiciona OR entre valores de status.
EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM orders
WHERE tenant_id = $1 AND (status = 'open' OR status = 'pending');Sinais FAIL na saída:
Seq Scan on orders (cost=0..250000 rows=1200000)
Buffers: shared read=180000
Planning Rows: 50000 Actual Rows: 890000Saída da Skill:
## Veredito: FAIL
### Problemas
1. Seq Scan - filtro em tenant_id + status deveria usar índice
2. Estimativa de linha errada em 18x - execute ANALYZE orders
3. OR impede uso simples de btree composto - considere reescrita para IN (...)
### Correção Sugerida
```sql
SELECT * FROM orders
WHERE tenant_id = $1 AND status IN ('open', 'pending');CREATE INDEX CONCURRENTLY idx_orders_tenant_status
ON orders (tenant_id, status);
## Mergulho Profundo
### Rubrica de Aprovação/Rejeição
| Sinal | Aprova | Falha |
| --- | --- | --- |
| Caminho de acesso | Index Scan / Index Only Scan no filtro | Seq Scan > 10k linhas |
| Join | Hash/Merge em grandes conjuntos com chaves de equi-join | Nested Loop com seq scan interno |
| Sort | Heap scan Top-N com índice | Sort externo em milhões |
| Buffers | Estável vs frequência de chamada | Lê a tabela inteira por requisição |
### Anexos de PR Necessários
```sql
-- Contexto da escala da tabela
SELECT relname, n_live_tup, pg_size_pretty(pg_relation_size(oid))
FROM pg_class c JOIN pg_stat_user_tables s ON s.relid = c.oid
WHERE relname = 'orders';
SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables WHERE relname = 'orders';
ANALYZE orders; -- staging antes do EXPLAIN se estiver desatualizadopg_indexes antes do DDL.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
auto_explain | Amostrar planos em logs | Revisão de PR antes do merge |
| UI de plano pganalyze | Monitoramento contínuo | Revisão em ambiente air-gapped |
| Sessão de pareamento | Primeiro PR de autor júnior | CRUD trivial rotineiro |
Sim, quando seletividade moderada e múltiplos predicados se combinam. Falha quando o bitmap cobre a maior parte da tabela repetidamente em QPS alto.
10x entre planejado e real dispara investigação de estatísticas ou estatísticas estendidas. 2x pode ser aceitável em tabelas voláteis.
Recomenda; Migration Safety Skill pontua o risco de lock antes do merge.
Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 e cliente psql 18.4.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026