sql-optimizer
Viprasol-Tech/sql-optimizer
AI agent skill for SQL tuning — read EXPLAIN ANALYZE plans, propose composite/covering/partial indexes, catch N+1 / OFFSET / LIKE-%prefix anti-patterns, with re-measure protocol. PostgreSQL & MySQL. Works with Claude Code, Codex, Cursor. By Viprasol Tech.
Instalação
npx convez-ai Viprasol-Tech/sql-optimizer1 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
README
A tradução para o português deste README ainda está na fila.
SQL Optimizer — Agent Skill
Make slow SQL fast: read the
EXPLAIN ANALYZEplan, find the single worst node, propose the right index (composite, covering, partial), and ship a re-measure protocol. PostgreSQL + MySQL 8.
Works with: Claude Code · OpenAI Codex · Cursor · GitHub Copilot · Gemini CLI · 26+ tools that support portable agent skills.
Quick Install
Clone the skill into your agent's skills directory:
# Claude Code
git clone https://github.com/Viprasol-Tech/sql-optimizer \
~/.claude/skills/sql-optimizer
# OpenAI Codex
git clone https://github.com/Viprasol-Tech/sql-optimizer \
~/.codex/skills/sql-optimizer
# Cursor / Gemini CLI / other tools — clone anywhere your tool loads skills from, e.g.
git clone https://github.com/Viprasol-Tech/sql-optimizer \
~/.config/skills/sql-optimizer
The skill is a single self-contained skill.md (plus examples) — no
dependencies, no install step, nothing to build.
Try It
Paste a slow query and its EXPLAIN ANALYZE and ask:
Why is this query slow and what index do I need?
The skill will scope your engine + schema + cardinalities, read the plan
node-by-node, identify the worst node (highest actual_time × loops or
biggest Rows Removed by Filter), propose the exact CREATE INDEX DDL
(with CONCURRENTLY where appropriate), warn about write amplification
and EXPLAIN ANALYZE DML pitfalls, and hand you a re-measure protocol.
Why This Exists
Most "slow query" tickets come down to a small number of patterns: a
missing or wrong-order composite index, a stale-statistics cardinality
miss, a sort spilling to disk, or an N+1 hidden in an ORM. Senior DBAs
have a consistent workflow for these — reproduce on real data, capture
the plan, find the single worst node, hypothesize one fix, ship it,
re-measure on hot and cold cache. Junior optimizers tend to shotgun
CREATE INDEX statements at the problem and hope. This skill encodes the
senior workflow so your agent runs it the same way every time, without
hallucinating indexes or skipping the re-measure step.
What It Does
- Scopes the tuning — engine and version, query, schema with
existing indexes, row counts, the
EXPLAINoutput if any, and what "slow" means in latency terms. - Reads the plan with the full operator glossary — Seq / Index /
Index-Only / Bitmap / Nested-Loop / Hash / Merge / Sort /
HashAggregate / Materialize / CTE Scan — plus the two diagnostic
rules (Plan Rows vs Actual mismatch ⇒ stale stats;
Rows Removed by Filter⇒ over-fetching). - Proposes the right index — composite with correct column order
(equality → range → sort, the leftmost-prefix rule), covering /
INCLUDE, partial, expression — with the exactCREATE INDEX [CONCURRENTLY]DDL. - Catches anti-patterns — N+1,
OFFSETover five-figure values,ORchains,NOT INwith NULLs,LIKE '%abc%',SELECT *in hot paths, scalar subqueries inSELECT, megaIN (...)lists. - Tunes the knobs —
work_mem,shared_buffers,effective_cache_size(PG);innodb_buffer_pool_size(MySQL);default_statistics_targetand extended stats / histograms. - Outputs a tuning report — verdict banner (✅ / 🟡 / 🟠 / ⛔), plan summary table, diagnosis, ordered fix plan with DDL, re-measure protocol, and risk notes (build time, lock impact, write amplification, parameter sniffing).
Features
- Honest scope — no live DB access; reasons over the query, EXPLAIN output, DDL, and row counts you provide. Plans are data- and config-dependent; always re-EXPLAIN on prod-sized data.
- DML safety warning baked in — ⚠️
EXPLAIN ANALYZEonINSERT/UPDATE/DELETEactually performs the write. Wrap inBEGIN; ... ROLLBACK;or use a clone. - 12 indexing pitfalls condensed — low-cardinality, function-wrap,
ORchains, implicit cast, wrong column order, over-indexing, skew without stats, stale stats,LIKE '%x', missing partial, dead indexes, invalid after failedCONCURRENTLY. - N+1 detection + 4 fixes — eager loading (Rails / Django / Hibernate
/ EF Core / SQLAlchemy), batch
IN (...), single JOIN with grouped aggregate, GraphQL DataLoader. - 2025 features — PG JIT / parallel / partitioning; MySQL 8 hash join, invisible indexes, histograms; prepared statements + plan stability caveat.
Workflow at a glance
| Step | Action | Why |
|---|---|---|
| 1 | Reproduce on prod-sized data | Dev datasets pick the wrong plan |
| 2 | EXPLAIN (ANALYZE, BUFFERS) | Estimates lie; actuals + buffers don't |
| 3 | Find the worst node | One node usually owns the latency |
| 4 | Hypothesize ONE fix | Two changes = no signal |
| 5 | Apply & re-EXPLAIN | Confirm the plan changed |
| 6 | Re-measure hot AND cold cache | Hot run hides disk cost |
See full worked reports in examples/:
- Postgres slow query — Seq Scan over
50M-row
users, 200M-row hash-join probe, sort spilling to disk. Three fixes (composite predicate index, join-side index withINCLUDE,work_membump), exact DDL, expected post-fix plan, and risk notes. - ORM N+1 — Django view firing
12,438
COUNT(*)queries per minute. Diagnosed viapg_stat_statements, collapsed into one query withannotate(Count(...))(orprefetch_relatedif rows are needed).
Not a Substitute for a Production DBA
This skill provides educational engineering guidance — not a
guarantee of performance, not a substitute for production APM, slow-query
monitoring, or a qualified DBA on critical systems. Plans are data- and
config-dependent and change with version, statistics, and load.
Always re-run EXPLAIN (ANALYZE, BUFFERS) on prod-sized data, on
both hot and cold caches, before declaring a fix shipped. Index changes
slow writes — verify the win. ⚠️ EXPLAIN ANALYZE on DML performs the
write; wrap in BEGIN; ... ROLLBACK; or run on a clone. Not
affiliated with or endorsed by Anthropic.
Contact — Viprasol Tech Private Limited
- 🌐 Website: viprasol.com
- ✉️ Email: support@viprasol.com
- 💬 Telegram: t.me/viprasol_help · 📱 WhatsApp: +91 96336 52112
- 🐙 GitHub: @Viprasol-Tech · 💼 LinkedIn · 𝕏 @viprasol
Viprasol Tech — fintech software, AI agents, algorithmic trading systems, and B2B SaaS.
License
MIT © 2025 Viprasol Tech Private Limited