Validate AI-generated SQL for semantic correctness

sqlsure catches SQL that is perfectly valid, runs without error, and returns a number that is silently wrong - revenue double-counted by a join, an average summed instead of weighted, a patient identifier exposed - the kind of bug that databases, linters, and an LLM reviewing its own SQL all miss. sqlsure catches it deterministically, in about 0.1ms, before the query runs, by judging SQL against facts a team has already declared: dbt unique tests become grain, relationships tests become join cardinality, and one-line meta tags mark what's safe to sum. There's no new modeling language to learn and no model to maintain by hand - the rules are dictionary lookups against a SemanticModel, not LLM calls, so the same SQL and the same rulebook always produce the same verdict, offline.

Nine rules ship in v0.1: FANOUT (SUM/COUNT of an additive measure after a one-to-many join), CHASM (two or more fan-out joins multiplying each other), ADDITIVITY (summing a non-additive measure like a rate or average), SEMI_ADDITIVE (balances or censuses summed across their snapshot dimension), JOIN_KEY (a join on columns matching no declared relationship), and CROSS_JOIN (a join with no predicate) as errors; WEIGHTED_AVG (an AVG silently re-weighted by fan-out) and UNDECLARED_JOIN (a join with no declared relationship - unverifiable, not assumed safe) as warnings; and SENSITIVE_COLUMN (a PHI/PII column exposed in output) as a policy flag. When sqlsure can't verify something against the declared model, it reports "can't verify," never "looks fine" - honest uncertainty is treated as a feature, not a gap to paper over.

Every rejection carries a machine-actionable fix, so an AI agent can self-repair in a draft-check-fix-check-execute loop; the source reports that applying the suggested fix verbatim produced a passing query 10 out of 10 times in its benchmark. Run over the gold-answer sets of the two benchmarks text-to-SQL models are graded on (Spider and BIRD), sqlsure flagged 45 issues across 2,568 expert-written queries with zero false alarms - including one BIRD dev gold answer provably wrong by 8x from exactly the bug class sqlsure targets, and a schema defect now filed upstream against the benchmark itself.

Use sqlsure wherever SQL is generated by an AI agent or a text-to-SQL product and needs a deterministic semantic check before execution or merge - as a CI gate blocking a PR that double-counts, as an MCP server an agent must pass inspection through before running a query, or embedded as a library (check()) inside a text-to-SQL product or agent framework, including drop-in wrappers for Vanna/WrenAI-style generators. It's also useful standalone, auditing an entire dbt repo for latent semantic risk (python -m sqlsure.scan path/to/dbt-repo --report report.md).

It is not a data-access or execution-correctness tool: it parses query text only, never connects to a database, and it validates semantics against a declared model rather than checking whether a query is syntactically valid or returns the "right" row count. It also depends on having (or being able to introspect) a semantic model - dbt tests, PK/FK declarations, or a live database catalog - so a schema with no declared relationships and no introspectable catalog gives it nothing to check against beyond the rules that don't require declared joins.

Install and check a query against a semantic model:

pip install sqlsure

from sqlsure import SemanticModel, check
violations = check(sql, model)   # [] means semantically safe

Input is a SQL query plus a SemanticModel, sourced from dbt's manifest.json/schema.yml (works today, zero extra config), plain PK/FK declarations, hand-written JSON (model.example.json), a live database's own catalog via sqlsure.introspect (model_from_sqlite() for SQLite PRAGMAs, or information_schema for Postgres/MySQL), or OSI/WrenAI MDL loaders. Output is a list of violations (empty means semantically safe), each carrying a rule name, severity (error, warning, or policy), and a machine-actionable fix suggestion. The CLI (python -m sqlsure.cli --model model.json query.sql) exits 1 on violations for CI gating, and python -m sqlsure.scan produces a Markdown audit report across a whole dbt repository.

sqlsure runs as a CI gate, an MCP server (claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json) that an AI agent must pass before executing a query, a Python library for embedding check() inside any text-to-SQL product, or a standalone Agent Skill (a single SKILL.md an agent can load directly with no server process). It reads semantic models from dbt, plain PK/FK declarations, live database introspection (SQLite, Postgres, MySQL), hand-written JSON, and working loaders for the OSI spec and WrenAI's MDL format; Cube and Snowflake Semantic Views adapters are on the roadmap. Documented integration points include a GitHub Action, pre-commit hook, Snowflake UDF / Cortex Agent tool, and query-history audit.

Teams building or operating AI agents and text-to-SQL products who need a deterministic, offline check that a generated query is semantically correct - not just syntactically valid - before it runs or merges, especially where a wrong-but-plausible number (double-counted revenue, an improperly averaged rate, an exposed PII column) would be a real business or compliance risk that no linter or self-review by the generating LLM would catch. It is licensed under Apache-2.0.