DEV Community: Yongho Hwang

[query-inspector] A Claude Code skill for extracting and tuning SQL/ORM queries

Yongho Hwang — Tue, 06 Oct 2026 07:13:37 +0000

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.

Stop writing Excel reports cell by cell - bind data to templates instead (Kotlin/Java)

Yongho Hwang — Tue, 06 Oct 2026 06:43:47 +0000

Still crafting Excel reports cell by cell with POI?

If you've ever built Excel reports in a JVM environment, you know the pain of Apache POI.

// Using Apache POI directly...
val workbook = XSSFWorkbook()
val sheet = workbook.createSheet("Employee Status")
val headerRow = sheet.createRow(0)
headerRow.createCell(0).setCellValue("Name")
headerRow.createCell(1).setCellValue("Position")
headerRow.createCell(2).setCellValue("Salary")

employees.forEachIndexed { index, emp ->
    val row = sheet.createRow(index + 1)
    row.createCell(0).setCellValue(emp.name)
    row.createCell(1).setCellValue(emp.position)
    row.createCell(2).setCellValue(emp.salary.toDouble())
}

// Column widths, styles, formulas, charts... it never ends

One header, one cell, one style at a time... hundreds of lines for a single report.

Add charts, conditional formatting, formulas, and images on top? The code spirals out of control.

TBEG (Template Based Excel Generator) solves this at its root - design the report in Excel, then just bind your data.

What is TBEG?

A JVM library that generates reports by binding data to Excel templates.

The core idea is simple:

A designer (or you) designs the report layout directly in Excel
Place ${variableName} markers where data should go
In your code, just pass the data
TBEG combines template + data to produce the final report

// Using TBEG - this is all you need to do
val data = mapOf(
    "title" to "Employee Status",
    "employees" to employeeList
)

ExcelGenerator().use { generator ->
    val bytes = generator.generate(template, data)
    File("output.xlsx").writeBytes(bytes)
}

Formatting, charts, formulas, and conditional formatting are all managed in the template. Your code focuses solely on data binding.

Design Philosophy

We don't reinvent what Excel already provides - we use it as-is.

Aggregation with Excel's =SUM() formula, averages with =AVERAGE()
Conditional highlighting with conditional formatting
Visualization with charts

Use the familiar Excel features as they are.

TBEG adds dynamic data binding on top, and automatically adjusts these features to work as intended even when data expands.

At a Glance

Template

Code

val data = simpleDataProvider {
    value("reportTitle", "Q1 2026 Sales Performance Report")
    value("period", "Jan 2026 ~ Mar 2026")
    value("author", "Yongho Hwang")
    value("reportDate", LocalDate.now().toString())
    image("logo", logoBytes)
    imageUrl("ci", "https://example.com/ci.png")  // URL supported
    items("depts") { deptList.iterator() }
    items("products") { productList.iterator() }
    items("employees") { employeeList.iterator() }
}

ExcelGenerator().use { generator ->
    generator.generateToFile(template, data, outputDir, "quarterly_report")
}

Result

Variable substitution, image insertion, repeat data expansion, automatic cell merge, formula range adjustment, conditional formatting duplication, and chart data reflection - TBEG handles all of this automatically.

Key Features

Feature	Description
Template-based generation	Generate reports by binding data to Excel templates
Repeat data processing	Expand list data into rows/columns with ${repeat(...)} syntax
Variable substitution	Bind values to cells, charts, shapes, headers/footers, formula arguments.
Image insertion	Insert dynamic images via byte arrays or URLs
Automatic cell merge	Auto-merge consecutive cells with the same value in repeat data
Bundle	Group multiple elements into a single unit that moves together
Selective field visibility	Restrict visibility of specific fields based on conditions. Choose between DELETE or DIM modes
Formula auto-adjustment	Automatically update formula ranges (SUM, AVERAGE, etc.) on data expansion
Automatic conditional formatting	Automatically apply original conditional formatting to repeated rows
Automatic data validation expansion	Automatically apply original data validation (dropdowns, etc.) to repeated rows
Chart/pivot table auto-reflection	Automatically reflect expanded data ranges in charts. Pivot table source range auto-adjustment
File encryption	Set open password for generated Excel files
Document metadata	Set document properties such as title, author, keywords, etc.
Large-scale processing	Reliably process over 1 million rows with low CPU utilization
Asynchronous processing	Process large data in the background
Lazy loading	Memory-efficient data processing via DataProvider
Spring Boot support	Easy integration with auto-configuration

Template Syntax Preview

Syntax	Description	Example
${variableName}	Variable substitution	${title}
${object.field}	Repeat item field	${emp.name}
${repeat(collection, range, object)}	Repeat processing	${repeat(items, A2:C2, item)}
${image(name)}	Image insertion	${image(logo)}
${merge(object.field)}	Automatic cell merge	${merge(emp.dept)}
${bundle(range)}	Bundle	${bundle(A5:H12)}
${hideable(object.field, range, mode)}	Selective field visibility	${hideable(emp.salary, C1:C3, DIM)}

Performance

TBEG internally generates data using streaming, producing 1 million rows in about 3.2 seconds while using around 9% of system CPU. Both rendering and post-processing operate in streaming mode, using a constant memory buffer regardless of data size.

Data Size	Time	CPU Usage
1,000 rows	13ms	25.0%
10,000 rows	47ms	17.4%
30,000 rows	117ms	13.8%
100,000 rows	354ms	11.6%
1,000,000 rows	3,203ms	9.0%

Comparison with Other Libraries (100,000 rows)

Library	Time
TBEG	0.35s
JXLS (STREAMING_ON)	0.73s
(ref.) JXLS (STREAMING_OFF)	2.63s

The direct comparison target is JXLS STREAMING_ON, which shares the same output conditions. STREAMING_OFF (full in-memory mode) is a reference figure.

Most Common Use Case: Excel Download API

In practice, TBEG is most frequently used for Excel download features in web applications.

@GetMapping("/api/reports/download")
fun downloadReport(response: HttpServletResponse) {
    val data = reportService.getReportData()
    val template = resourceLoader.getResource("classpath:templates/report.xlsx")

    response.contentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    response.setHeader("Content-Disposition", "attachment; filename=report.xlsx")

    excelGenerator.generate(template.inputStream, data)
        .let { response.outputStream.write(it) }
}

Admin page list exports, settlement report downloads, monthly report generation - set up one template and this is all the code you need.

When to Use TBEG

✅ Generating standardized reports/statements
✅ Filling data into Excel forms provided by a designer
✅ Reports requiring complex formatting (conditional formatting, charts)
✅ Processing large datasets with tens to hundreds of thousands of rows
✅ Tables where the number of rows or columns changes with the data
✅ Implementing Excel download APIs in Spring Boot environments
❌ Reading/parsing Excel files (TBEG is generation-only)

Getting Started

Add Dependency

// build.gradle.kts
dependencies {
    implementation("io.github.jogakdal:tbeg:1.2.5")
}

// Gradle (Groovy DSL)
dependencies {
    implementation 'io.github.jogakdal:tbeg:1.2.5'
}

<!-- Maven -->
<dependency>
    <groupId>io.github.jogakdal</groupId>
    <artifactId>tbeg</artifactId>
    <version>1.2.5</version>
</dependency>

The version above is as of this writing. Check the latest version on Maven Central.

Quick Start (Kotlin)

import io.github.jogakdal.tbeg.ExcelGenerator
import java.io.File

data class Employee(val name: String, val position: String, val salary: Int)

fun main() {
    val data = mapOf(
        "title" to "Employee Status",
        "employees" to listOf(
            Employee("Yongho Hwang", "Director", 8000),
            Employee("Yongho Han", "Manager", 6500)
        )
    )

    ExcelGenerator().use { generator ->
        val template = File("template.xlsx").inputStream()
        val bytes = generator.generate(template, data)
        File("output.xlsx").writeBytes(bytes)
    }
}

Quick Start (Java)

import io.github.jogakdal.tbeg.ExcelGenerator;
import java.io.*;
import java.nio.file.*;
import java.util.*;

public class Example {
    public static void main(String[] args) throws Exception {
        var data = Map.<String, Object>of(
            "title", "Employee Status",
            "employees", List.of(
                Map.of("name", "Yongho Hwang", "position", "Director", "salary", 8000),
                Map.of("name", "Yongho Han", "position", "Manager", "salary", 6500)
            )
        );

        try (var generator = new ExcelGenerator()) {
            byte[] bytes = generator.generate(
                new FileInputStream("template.xlsx"), data);
            Files.write(Path.of("output.xlsx"), bytes);
        }
    }
}

Learn More

This is the first post in the TBEG series. In the next post, we'll walk through creating a template and binding data step by step.

GitHub: jogakdal/data-processors-with-excel
Maven Central: tbeg

📖 Documentation

⭐ Found TBEG useful? Star it on GitHub - it really helps the project grow.