convez.ai
Skill
Viprasol-Tech

sql-optimizer

Viprasol-Tech/sql-optimizer

Ver no GitHub
InicialPluginScore · de 0 a 100

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-optimizer

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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 ANALYZE plan, find the single worst node, propose the right index (composite, covering, partial), and ship a re-measure protocol. PostgreSQL + MySQL 8.

GitHub stars License: MIT Agent Skills Engines Covers Version

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

  1. Scopes the tuning — engine and version, query, schema with existing indexes, row counts, the EXPLAIN output if any, and what "slow" means in latency terms.
  2. 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).
  3. Proposes the right index — composite with correct column order (equality → range → sort, the leftmost-prefix rule), covering / INCLUDE, partial, expression — with the exact CREATE INDEX [CONCURRENTLY] DDL.
  4. Catches anti-patterns — N+1, OFFSET over five-figure values, OR chains, NOT IN with NULLs, LIKE '%abc%', SELECT * in hot paths, scalar subqueries in SELECT, mega IN (...) lists.
  5. Tunes the knobs — work_mem, shared_buffers, effective_cache_size (PG); innodb_buffer_pool_size (MySQL); default_statistics_target and extended stats / histograms.
  6. 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 ANALYZE on INSERT / UPDATE / DELETE actually performs the write. Wrap in BEGIN; ... ROLLBACK; or use a clone.
  • 12 indexing pitfalls condensed — low-cardinality, function-wrap, OR chains, implicit cast, wrong column order, over-indexing, skew without stats, stale stats, LIKE '%x', missing partial, dead indexes, invalid after failed CONCURRENTLY.
  • 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

StepActionWhy
1Reproduce on prod-sized dataDev datasets pick the wrong plan
2EXPLAIN (ANALYZE, BUFFERS)Estimates lie; actuals + buffers don't
3Find the worst nodeOne node usually owns the latency
4Hypothesize ONE fixTwo changes = no signal
5Apply & re-EXPLAINConfirm the plan changed
6Re-measure hot AND cold cacheHot 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 with INCLUDE, work_mem bump), exact DDL, expected post-fix plan, and risk notes.
  • ORM N+1 — Django view firing 12,438 COUNT(*) queries per minute. Diagnosed via pg_stat_statements, collapsed into one query with annotate(Count(...)) (or prefetch_related if 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

Viprasol Tech — fintech software, AI agents, algorithmic trading systems, and B2B SaaS.

License

MIT © 2025 Viprasol Tech Private Limited

Ver o original no GitHub

Bom para

Relacionados