Noções Básicas de EXPLAIN

EXPLAIN mostra o caminho de acesso escolhido pelo planejador antes de você arcar com o custo de execução de uma consulta. EXPLAIN (ANALYZE, BUFFERS) executa a consulta e adiciona tempos e I/O de buffer para que você possa ver o que realmente aconteceu no PostgreSQL 18.4.

Receita

Cartão de referência rápida - pronto para copiar e colar.

EXPLAIN (ANALYZE, BUFFERS, VERBOSE, SETTINGS, WAL)
SELECT o.id, o.total
FROM orders o
WHERE o.status = 'shipped'
  AND o.created_at >= now() - interval '7 days';

Quando usar isso: Qualquer consulta lenta ou surpreendente em um conjunto de dados semelhante à produção. Capture o plano antes e depois de alterações de índice ou estatísticas.

Exemplo de Trabalho

CREATE TABLE orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id bigint NOT NULL,
  status text NOT NULL DEFAULT 'pending',
  created_at timestamptz NOT NULL DEFAULT now(),
  total numeric(12,2) NOT NULL
);
 
CREATE INDEX orders_status_created_idx ON orders (status, created_at);
 
INSERT INTO orders (customer_id, status, created_at, total)
SELECT
  (random() * 10000)::bigint,
  CASE WHEN random() < 0.05 THEN 'shipped' ELSE 'pending' END,
  now() - (random() * interval '90 days'),
  (random() * 500)::numeric(12,2)
FROM generate_series(1, 200000);
 
ANALYZE orders;
 
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT id, total
FROM orders
WHERE status = 'shipped'
  AND created_at >= now() - interval '7 days';

Um plano saudável geralmente mostra Index Scan em orders_status_created_idx com baixos rows removed by filter e contagens modestas de shared hit.

O que isso demonstra:

• ANALYZE antes de comparar planos
• Leitura do tipo de scan e nome do índice
• Interpretação de actual time e rows versus estimativas do planejador
• Uso de BUFFERS para identificar cache misses

Mergulho Profundo

Como Funciona

• O planejador constrói uma árvore de nós (scan, join, sort, aggregate). Cada nó tem contagens de linhas estimadas e reais.
• EXPLAIN sozinho é barato e seguro em produção. ANALYZE executa a consulta, então use-o em staging ou com guardas LIMIT em instruções destrutivas.
• BUFFERS relata shared hit (cache) e shared read (disco). Alto read em uma consulta frequente significa que mais RAM ou melhor indexação podem ajudar.
• SETTINGS (PostgreSQL 12+) mostra GUCs não padrão que influenciaram o plano, útil quando random_page_cost ou work_mem diferem por role.

Opções de EXPLAIN em Resumo

Notas SQL

-- Salva um plano para um ticket (sem execução)
EXPLAIN (FORMAT JSON)
SELECT count(*) FROM orders WHERE status = 'pending';
 
-- Compara apenas estimativas (seguro em produção)
EXPLAIN (VERBOSE)
SELECT * FROM orders WHERE customer_id = 42;

Armadilhas

• Executar EXPLAIN ANALYZE em DELETE/UPDATE sem cuidado - Você modifica dados de produção. Correção: Envolva em uma transação e ROLLBACK, ou teste em um snapshot.
• Confiar em números de cache frio uma vez - A primeira execução após a reinicialização parece pior do que o estado estável. Correção: Execute duas vezes; compare o segundo resultado de ANALYZE.
• Ignorar a deriva da estimativa de linhas - rows=1000 vs actual rows=85000 sinaliza estatísticas ruins ou predicados correlacionados. Correção: ANALYZE e verifique estatísticas estendidas.
• Ler apenas o tempo total - Um nó externo barato pode esconder um loop aninhado caro por dentro. Correção: Encontre o nó com a maior participação em actual time.
• Esquecer search_path - Os planos diferem quando a qualificação do esquema muda. Correção: Defina search_path explicitamente na sessão que você captura.

Alternativas

FAQs

Relacionado

• Seq Scan vs Index Scan - Quando cada scan vence
• Nested Loop, Hash Join, Merge Join - Nós de join em planos
• Estudos de Caso de Planos Ruins - Padrões reais de estimativa incorreta
• Noções Básicas de Estatísticas - Por que as estimativas dão errado

Versões de Pilha: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.