query-inspector：在提交前提取并调优 SQL/ORM 查询的 Claude Code Skill

query-inspector is a Claude Code skill that extracts the SQL/ORM queries from your project's source, then diagnoses and tunes missing indexes / N+1 problems / anti-patterns.

Queries that run fine until the data piles up. N+1 problems that sail through code review. The real SQL your ORM generates, invisible in the code. It catches all of this right before you commit, not after it reaches production.

Common pitfalls

• A query shipped without an index suddenly turns into a full scan once there are tens of thousands of rows.
• An N+1 problem slips through code review, and a single list API fires dozens of queries.
• You can't tell from the code alone what SQL JPA or QueryDSL will actually generate.
• Code review looks at logic, not "the queries this change will produce" from a SQL angle.
• QA rarely catches it either, because its test data is too small for a missing index or an N+1 to surface as a slowdown.

These problems share one trait: they surface only after you ship.

query-inspector moves that moment to just before the commit.

Overview

It's a Claude Code plugin, made of two skills:

• tuning-report - extracts the SQL/ORM queries in your git changes, diagnoses missing indexes / N+1s / anti-patterns, and produces a report with fixes you can apply right away.
• inventory-report - catalogs the queries your project runs, down to the full query body and index coverage.

Neither one touches your code; they only produce reports.

Run it right before a commit, and it surfaces performance problems that would otherwise appear only after you ship.

Highlights

There were already ways to check query performance: runtime SQL logging (p6spy, Hibernate statistics) or APM. But those surface a problem only after the query runs.

query-inspector checks before anything runs, on the changes you're about to commit. Inferring the SQL an ORM will generate without executing it is an approach that only became practical with recent advances in AI.

Only your changes, in your commit flow

It analyzes only what changed since your last tuning, not the whole project every time. That keeps it fast and lets it sit naturally in your usual git add -> run query-inspector -> commit flow.

A full-project scan is available too.

SQL the code doesn't directly reveal

Explicit SQL is taken as-is, and for JPA derived methods / @Query / QueryDSL / Kotlin JDSL / MyBatis dynamic queries it infers the SQL that will actually be generated, then analyzes or catalogs it.

Every query carries an EXACT / INFERRED / AMBIGUOUS confidence label, so you know how far to trust each one.

From static analysis to a live EXPLAIN - as deep as you want

Even without a database it catches most problems (missing indexes / N+1s / SQL-dialect mismatches / anti-patterns).

It connects to your development database and runs a real EXPLAIN only when you want more certainty.

For safety, production hosts are blocked by default, and only read-only queries run.

Reports you can act on immediately

It doesn't stop at "this might be slow."

You get a CREATE INDEX statement with the right column order, the exact file:line, and copy-ready Action Items.

A developer, or the AI assisting that developer, can read the report and start fixing right away.

Follow-up on past suggestions

It compares the previous run's suggestions against your current code and flags the ones still not applied.

Even files you didn't touch this run are included in the check.

JVM-first stacks, localized reports

The current version focuses on Kotlin/Java (JPA, Hibernate, QueryDSL, MyBatis, native SQL). Python (Django/SQLAlchemy) is supported too, though not as thoroughly validated as the primary stacks.

More stacks are planned.

SQL dialects (MySQL/MariaDB, PostgreSQL) are auto-detected.

Reports come out in the language you're chatting with Claude in (you can also force a specific one).

Sample reports

A slice of what tuning-report produces after scanning your changes:

# Query Tuning Report - incremental (2 changed files)
- Severity (open): 🔴 3 / 🟡 2 / ⚪ 1   /   Follow-up: ✅ 2 resolved / ⚠️ 2 still open

## 🔴 [critical] Missing index - FK `orders.user_id` - OrderMapper.xml
- Why critical: it is the N+1 child query, so every user triggers a full scan of `orders`.
- Suggestion:  CREATE INDEX idx_orders_user_id ON orders (user_id);
- Verify (live EXPLAIN): `type: ALL -> ref`.

Point the same project at inventory-report and it lists the queries as a catalog instead of tuning:

# Query Inventory
- Queries: 24 ( SELECT 18 / INSERT 3 / UPDATE 2 / DELETE 1 )

#### [order-03] Orders for a given user
- Source: OrderMapper.xml:42 (selectOrdersByUser) / Type: SELECT
- Target: orders / Access columns: WHERE user_id, ORDER BY created_at
- Index coverage: ❌ uncovered (no index on user_id)

Use the tuning report to find what to fix, and the inventory to see everything that runs.

Getting started

Install and usage are in the GitHub README: github.com/jogakdal/query-inspector

If you have Claude Code, you can install it with these two commands:

claude plugin marketplace add jogakdal/query-inspector
claude plugin install query-inspector@query-inspector-marketplace

Want to see the output first? Browse the sample report and the Docker example in the repo.

It's still v1.0.0. After trying it, please file feedback via GitHub issues and it'll go into the next iteration; a star is welcome if you find it useful.

Run it before your next commit.