sqlsure

AI writes your SQL. sqlsure makes sure it's right.
A query can be perfectly valid, run without error, and return a number
that's silently wrong โ revenue double-counted by a join, an average
summed, a patient identifier exposed. Databases don't catch this.
Linters don't catch this. LLMs reviewing their own SQL don't catch this.
sqlsure does โ deterministically, in 0.1 ms, before the query runs.
Proof, not promises: we ran sqlsure over the gold answers of the two
benchmarks every text-to-SQL model is graded on. 2,568 expert-written
queries, 45 flags, zero false alarms โ including a BIRD dev gold answer
that is provably wrong by 8ร from the exact
bug class sqlsure targets, and a schema defect
reported upstream and since fixed
โ BIRD's 2026 Mini-Dev release added exactly the two foreign keys we
reported, and its annotations now match the shipped databases on all 11
databases (how we verified).
How it works
sqlsure judges SQL against facts your team already declared โ dbt unique
tests become grain, relationships tests become join cardinality, one-line
meta tags mark what's safe to sum. No new language to learn, no model to
maintain by hand. Rules are dictionary lookups, not LLM calls: same input,
same verdict, every time, offline.
Every rejection carries a machine-actionable fix, so AI agents
self-repair: draft โ check โ fix โ check โ execute. In our benchmark,
applying the fix verbatim produced a passing query 10/10 times.
Quick start
from sqlsure import SemanticModel, check
violations = check(sql, model)
Or clone and run the 30-second demo:
python check.py
python -m sqlsure.scan path/to/dbt-repo --report report.md
Three doors, one engine
1. CI gate โ blocks the merge when a PR double-counts:
python -m sqlsure.cli --model model.json query.sql
2. MCP server โ your AI agent must pass inspection before executing:
claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json
See docs/MCP.md for tool reference and agent-loop patterns.
3. Library โ embed check() inside any text-to-SQL product or agent
framework. A drop-in SemanticGate wraps
Vanna/WrenAI-style generators; a
semantic eval metric scores NL2SQL output
where execution-accuracy is blind.
Also available as an Agent Skill โ
a single SKILL.md your agent loads directly; no server process needed.
The rules (v0.1)
| Rule | Severity | Catches |
|---|
| FANOUT | error | SUM/COUNT of additive measure after one-to-many join |
| CHASM | error | two+ fan-out joins multiplying each other |
| ADDITIVITY | error | SUM of a non-additive measure (rates, averages) |
| SEMI_ADDITIVE | error | balances/censuses summed across their snapshot dimension |
| JOIN_KEY | error | join on columns matching no declared relationship |
| CROSS_JOIN | error | join with no predicate |
| WEIGHTED_AVG | warning | AVG silently re-weighted by fan-out |
| UNDECLARED_JOIN | warning | join with no declared relationship (unverifiable โ safe) |
| SENSITIVE_COLUMN | policy | PHI/PII column exposed in query output |
When sqlsure can't verify something, it says "can't verify" โ never "looks
fine." Honest uncertainty is a feature.
Trust properties
- Deterministic โ same SQL + same rulebook = same verdict, always;
rules are dictionary lookups, auditable line by line
- Offline โ zero network calls; your SQL never leaves your machine
- No data access โ parses query text; never connects to a database
- No telemetry โ nothing collected, ever (SECURITY.md)
- Supply chain โ releases ship exclusively via PyPI Trusted Publishing
(OIDC) from tagged commits with public CI runs; two runtime deps
Where the rulebook comes from
-
dbt (works today): manifest.json or schema.yml โ the tests teams
already wrote become enforceable semantics, zero config
-
Plain PK/FK declarations (works today โ powered the benchmark audits)
-
The live database itself (works today): no semantic layer at all?
sqlsure.introspect builds the rulebook from the catalog โ SQLite
PRAGMAs or information_schema PK/FK (postgres/mysql). Introspecting
BIRD's own database files recovered 2 foreign keys missing from the
benchmark's published schema โ reported upstream and fixed in BIRD's
2026 release
(bird-bench/mini_dev#37)
from sqlsure.introspect import model_from_sqlite
model = model_from_sqlite("app.db")
-
Hand-written JSON โ model.example.json
-
OSI and WrenAI MDL (working loaders in
integrations/): OSI
demonstrated on the spec's published examples;
WrenAI MDL demonstrated on WrenAI's own
shipped example manifest โ primaryKey โ grain, relationship
joinType + condition โ join edges, cube measures โ additivity
-
Cube, Snowflake Semantic Views โ adapters on the roadmap; the
engine only ever sees one SemanticModel
Validated on
- 16/16 rule tests, 100% recall / 0% false positives on the paired
benchmark (docs/METRICS.md)
- Real production repos (Mattermost's warehouse, Fivetran packages,
dbt's jaffle shop) โ docs/TEST-REPORTS.md
- Spider + BIRD gold queries โ the zero-noise external audit above
Learn more
Apache-2.0 ยท sqlsure.ai
mcp-name: io.github.sqlsure/sqlsure