convez.ai
SkillDados & AnalyticsIntermediário
yuribodo

Otimização de Queries PostgreSQL

yuribodo/postgres-query-optimization-skill

Otimize PostgreSQL com medição, não adivinhação — passo a passo

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Find the real offender — pg_stat_statements, ranked by total time (not per-call).
  2. Explain — capture the actual plan with EXPLAIN (ANALYZE, BUFFERS).
  3. Diagnose — locate the slowest node and why it's slow (Seq Scan, sort spill, bad estimate, unused index…).
  4. Fix the root cause — make the query sargable, design the right index, refresh stats, or tune config. One change at a time.
  5. Verify — re-run the plan and confirm the node changed and total time dropped.

Contents

FilePurpose
SKILL.mdCore 5-step methodology + a "I see X in the plan → likely cause" diagnostic table
REFERENCE.mdReading plans in depth (cost/rows/loops/buffers), scan & join nodes, index types and design rules, stats/maintenance
ANTIPATTERNS.mdSargability, 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

Ver o original no GitHub

Bom para

Relacionados