SQL Performance Copilot
A rule based SQL linter that parses queries into a syntax tree, flags common performance antipatterns and suggests rewrites, from a web app, a CLI or a GitHub Action.
- Role
- Author
- When
- May 2026 to present
- Stack
- Python, SQLGlot, FastAPI, TypeScript, Docker
- Source code private
Context
A lot of slow SQL is slow for the same handful of reasons: a function wrapped around an indexed column, a SELECT * that pulls columns nobody uses, a NOT IN against a column that can be NULL. These patterns can be spotted from the query text alone, before anyone runs EXPLAIN. I wanted a tool that does that check deterministically, without sending queries (which often reveal table and column names) to an external AI service.
What I built
Analysis engine. Queries are parsed into an abstract syntax tree with SQLGlot, and a set of rules walks the tree looking for known antipatterns. Each finding has a rule ID, an explanation and, where it is safe, a rewritten query shown as a before and after diff. Some examples from the rule catalogue:
| Rule | Pattern | Suggested fix |
|---|---|---|
Non sargable WHERE |
YEAR(created_at) = 2024 |
A date range on the bare column |
| Implicit join | FROM a, b WHERE ... |
Explicit JOIN ... ON |
Nullable NOT IN |
NOT IN (SELECT ...) |
NOT EXISTS |
| Count for existence | (SELECT COUNT(*) ...) > 0 |
EXISTS (SELECT 1 ...) |
High OFFSET |
OFFSET 100000 |
Keyset pagination |
There are general rules and dialect specific ones for PostgreSQL, MySQL and BigQuery (for example, a BigQuery scan without a partition filter). Each query also gets a score from 0 to 100 that sums up how many issues were found and how serious they are.
Three ways to use it.
- A web app (FastAPI backend, TypeScript and Vite frontend) to paste a query and read the report.
- A CLI,
spc-lint, that scans folders of.sqlfiles and outputs a table, JSON, Markdown or SARIF, with options to fail on a severity level or below a minimum score. - A GitHub Action that runs the CLI in CI and writes a SARIF report that GitHub code scanning can display.
The whole stack also runs with Docker Compose, and the repository has a test suite and CI workflow.
Design choice
The core of the tool is rule based (a few small classical models, trained offline, help with scoring). It cannot know your data distribution or indexes the way a query planner does, so its findings are hints, not verdicts. In exchange it is fast, gives the same answer every time and never needs a network connection or an API key.