---
id: analyze-performance
agent: data-engineer
title: Analisar performance do banco
inputs: [type, query, story]
outputs: [diagnóstico com explain plan/métricas, recomendações justificadas]
elicit: false
modes: [interactive, yolo]
---

# Analisar performance do banco

**Objetivo:** diagnosticar performance por evidência — explain plan e métricas reais — no tipo pedido
(`query`, `hotpaths` ou `interactive`), e recomendar mudanças justificadas, nunca por palpite.

**Pré-condições:**
- O `type` é `query` (uma query específica, exige `query`), `hotpaths` (queries mais custosas do
  workload) ou `interactive` (exploração guiada).
- Para `query`, a query foi fornecida. Para `hotpaths`, há estatísticas disponíveis
  (`pg_stat_statements` ou equivalente). Sem evidência, **pare** — não otimizo no escuro.

## Passos

1. **Capture a linha de base medida.** `query`: `EXPLAIN (ANALYZE, BUFFERS)` da query alvo. `hotpaths`:
   liste do `pg_stat_statements` as queries por tempo total/médio e por chamadas. Medição antes de
   qualquer hipótese.
2. **Leia o plano:** seq scans em tabela grande, sorts/hashes em disco, estimativas de linhas longe do
   real (estatísticas desatualizadas), loops aninhados caros, FK filtrada sem índice de suporte.
3. **Forme a hipótese de causa** ligada à evidência do plano — não à intuição. Ex.: "seq scan de 2M
   linhas no filtro `user_id` → falta índice".
4. **Recomende a mudança mínima que o plano justifica:** índice (com a coluna/ordem exata), reescrita
   da query, `ANALYZE` para atualizar estatísticas, ou desnormalização documentada. Um índice sem
   query que o justifique é peso morto — não recomendo.
5. **Estime o ganho e o custo:** o índice acelera leitura, mas pesa na escrita e em espaço. Registro o
   trade-off para a decisão ser informada.
6. **Emita o diagnóstico** com plano antes, causa, recomendação e ganho esperado. Aplicar índice =
   migration (snapshot → dry-run → apply) — fora desta task de análise.

## Critério de pronto (DoD)

- [ ] Linha de base medida (explain plan / métricas reais), não estimada
- [ ] Causa raiz ligada à evidência do plano
- [ ] Recomendação mínima e justificada, com trade-off escrita/espaço explícito
- [ ] Cada índice proposto serve a uma query real
- [ ] Diagnóstico emitido; nenhuma mudança aplicada nesta task

## Falha / recuperação

- **Sem `pg_stat_statements` (hotpaths)** → sinalizo a dependência e ofereço habilitá-la (via @devops
  se exigir config de infra) antes de prosseguir.
- **Plano não revela causa clara** → coleto mais evidência (estatísticas, distribuição de dados) antes
  de recomendar; não chuto índice.
- **Recomendação vira migration** → entrego o plano; aplicação segue snapshot → dry-run → apply, e o
  push é do @devops.