Otimização de Queries PostgreSQL
yuribodo/postgres-query-optimization-skill
Otimize PostgreSQL com medição, não adivinhação — passo a passo
Ver no GitHubSkill do Claude Code para diagnosticar e corrigir queries PostgreSQL lentas usando metodologia baseada em medição (EXPLAIN ANALYZE, indexação, sargability). Oferece um fluxo disciplinado de 5 passos: encontrar o gargalo real, explicar o plano, diagnosticar a causa raiz, aplicar a correção e verificar o resultado.
Instalação
npx convez-ai yuribodo/postgres-query-optimization-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Analisar planos de execução de queries lentas com EXPLAIN ANALYZE
- Projetar índices corretos baseado no diagnóstico real do problema
- Reescrever queries para torná-las sargable e eliminar anti-patterns
- Identificar e corrigir problemas de estatísticas e estimativas no PostgreSQL
Veredito

Skill bem-estruturado que ensina disciplina na otimização de banco de dados, evitando adivinhas e índices desnecessários. Material técnico sólido com metodologia clara, ideal para quem trabalha com PostgreSQL em produção.
README
A tradução para o português deste README ainda está na fila.
postgres-query-optimization
A Claude Code / Agent Skill for diagnosing and fixing slow PostgreSQL queries with a measure-first methodology — no guessing, no cargo-cult indexes.
What it does
Walks the agent through a disciplined optimization loop:
- Find the real offender —
pg_stat_statements, ranked by total time (not per-call). - Explain — capture the actual plan with
EXPLAIN (ANALYZE, BUFFERS). - Diagnose — locate the slowest node and why it's slow (Seq Scan, sort spill, bad estimate, unused index…).
- Fix the root cause — make the query sargable, design the right index, refresh stats, or tune config. One change at a time.
- Verify — re-run the plan and confirm the node changed and total time dropped.
Contents
| File | Purpose |
|---|---|
SKILL.md | Core 5-step methodology + a "I see X in the plan → likely cause" diagnostic table |
REFERENCE.md | Reading plans in depth (cost/rows/loops/buffers), scan & join nodes, index types and design rules, stats/maintenance |
ANTIPATTERNS.md | Sargability, concrete query rewrites, and common mistakes (N+1, deep OFFSET, OR, implicit casts, leading wildcards…) |
Install
Recommended — skills.sh CLI
From your project root:
npx skills add yuribodo/postgres-query-optimization-skill
Start a new Claude Code session and it's picked up automatically.
Manual — clone into your skills directory
git clone https://github.com/yuribodo/postgres-query-optimization-skill.git \
~/.claude/skills/postgres-query-optimization
Either way, the agent auto-discovers the skill and loads it whenever a PostgreSQL query needs tuning.
How it works
A Skill is a folder with a SKILL.md whose YAML front-matter has a name and a description. Claude reads only that description at session start — it's the trigger. When your request matches (a slow Postgres query, "read this EXPLAIN", "what index should I add?"), Claude loads SKILL.md and follows it.
This skill uses progressive disclosure to stay cheap on context: SKILL.md is short and holds the methodology; the heavier reference material lives in two extra files that Claude opens only when it needs them:
postgres-query-optimization/
├── SKILL.md # always loaded when triggered — the 5-step loop + diagnostic table
├── REFERENCE.md # opened when reading a plan deeply or designing an index
└── ANTIPATTERNS.md # opened when a query needs rewriting to be sargable
So a quick "which index?" question never pays for the full anti-pattern catalogue, but it's one hop away when the problem turns out to be a non-sargable predicate.
You can also invoke it explicitly with /postgres-query-optimization.
Philosophy
- Measure, don't guess — a plan must explain why before any change.
- Optimize by total time, not time-per-call.
- One change at a time, then re-measure.
- No free lunch — every index taxes writes and storage.
Sources
Built from Query Optimization for Mere Humans in PostgreSQL plus the official PostgreSQL docs, EnterpriseDB, Mydbops, TigerData, and community write-ups on sargability and anti-patterns.
License
MIT