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.

Receita

## 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 consulta

EXPLAIN (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:

ORM ou SQL escrito à mão em PR afeta caminho crítico (hot path)
pgbadger/pg_stat_statements sinalizou regressão após deploy
O conselheiro sugeriu índice que precisa de validação humana

Exemplo de Trabalho

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: 890000

Saí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');

Índice (se ausente)

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';

Frescor das Estatísticas

SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables WHERE relname = 'orders';
ANALYZE orders;  -- staging antes do EXPLAIN se estiver desatualizado

Armadilhas

EXPLAIN sem ANALYZE - mostra um plano barato que mente em tempo de execução. Correção: exigir ANALYZE em staging.
Tabela de staging vazia - index scan instantâneo em 0 linhas. Correção: popular staging ou usar snapshot de estatísticas de produção.
"Adicionar índice" genérico - duplicado de índice existente. Correção: diff de pg_indexes antes do DDL.
Ignorar custo de escrita - índice economiza leitura mas mata SLA de INSERT. Correção: notar taxa de escrita da tabela na saída.
EXPLAIN em produção em tabelas quentes - pega locks reais com algumas configurações. Correção: padrão para política de staging.

Alternativas

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

FAQs

Aceitar bitmap heap scan em vez de index scan?

Sim, quando seletividade moderada e múltiplos predicados se combinam. Falha quando o bitmap cobre a maior parte da tabela repetidamente em QPS alto.

Quão rigoroso com a deriva da estimativa de linha?

10x entre planejado e real dispara investigação de estatísticas ou estatísticas estendidas. 2x pode ser aceitável em tabelas voláteis.

A skill aprova DDL de índice de migração?

Recomenda; Migration Safety Skill pontua o risco de lock antes do merge.

Relacionados

Agent Skills Basics - estrutura da skill
EXPLAIN Basics - leitura de planos
Seq Scan vs Index Scan - caminhos de acesso
Code Review for SQL - requisitos de PR
Pairing on Query PRs - revisão ao vivo

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 e cliente psql 18.4.

EXPLAIN Review Skill

Receita

## 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 consulta

EXPLAIN (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:

ORM ou SQL escrito à mão em PR afeta caminho crítico (hot path)
pgbadger/pg_stat_statements sinalizou regressão após deploy
O conselheiro sugeriu índice que precisa de validação humana

Exemplo de Trabalho

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: 890000

Saí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');

Índice (se ausente)

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';

Frescor das Estatísticas

SELECT relname, last_analyze, last_autoanalyze
FROM pg_stat_user_tables WHERE relname = 'orders';
ANALYZE orders;  -- staging antes do EXPLAIN se estiver desatualizado

Armadilhas

EXPLAIN sem ANALYZE - mostra um plano barato que mente em tempo de execução. Correção: exigir ANALYZE em staging.
Tabela de staging vazia - index scan instantâneo em 0 linhas. Correção: popular staging ou usar snapshot de estatísticas de produção.
"Adicionar índice" genérico - duplicado de índice existente. Correção: diff de pg_indexes antes do DDL.
Ignorar custo de escrita - índice economiza leitura mas mata SLA de INSERT. Correção: notar taxa de escrita da tabela na saída.
EXPLAIN em produção em tabelas quentes - pega locks reais com algumas configurações. Correção: padrão para política de staging.

Alternativas

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

FAQs

Aceitar bitmap heap scan em vez de index scan?

Sim, quando seletividade moderada e múltiplos predicados se combinam. Falha quando o bitmap cobre a maior parte da tabela repetidamente em QPS alto.

Quão rigoroso com a deriva da estimativa de linha?

10x entre planejado e real dispara investigação de estatísticas ou estatísticas estendidas. 2x pode ser aceitável em tabelas voláteis.

A skill aprova DDL de índice de migração?

Recomenda; Migration Safety Skill pontua o risco de lock antes do merge.

Relacionados

Agent Skills Basics - estrutura da skill
EXPLAIN Basics - leitura de planos
Seq Scan vs Index Scan - caminhos de acesso
Code Review for SQL - requisitos de PR
Pairing on Query PRs - revisão ao vivo

Versões do Stack: Esta página foi escrita para PostgreSQL 18.4 e cliente psql 18.4.

EXPLAIN Review Skill

Buscar na documentação

EXPLAIN Review Skill