Sqlsure Semantic Checks for AI SQL

Sqlsure Overview

Sqlsure is a Python library that runs deterministic semantic checks on SQL queries before execution. The project

sqlsuresqlsure

appeared on Hacker News with claims that it caught 45 issues across 2,568 gold queries from the BIRD and Spider text-to-SQL benchmarks, including one case where an expert-written answer produced an 8× error. The tool accepts a semantic model derived from existing dbt tests and meta tags, then returns violations or an empty list. No LLM calls occur at check time.

Core Mechanisms

Sqlsure loads facts from a JSON model that records grain, join cardinalities, and additive measures. A dbt unique test becomes a grain declaration. A relationships test becomes a cardinality rule. One-line tags in the model mark columns that may be summed without duplication.

The check function walks the query AST once. It compares selected aggregates against declared additive columns, inspects join keys for declared relationships, and flags any column marked non-additive when it appears inside a SUM. Because every rule is a dictionary lookup, the same query always receives the same verdict in under a millisecond.

When a violation occurs, the library emits a machine-readable fix. The example output contains the exact rewritten clause that removes the offending column or adjusts the join. In the published benchmark, applying those fixes verbatim produced passing queries in all ten trials.

Usage Patterns

Install with pip install sqlsure. A minimal check looks like this:

from sqlsure import SemanticModel, check
model = SemanticModel.from_json("model.json")
violations = check(sql_text, model)

The repository also ships a CLI. python -m sqlsure.scan path/to/dbt-repo --report report.md walks an entire dbt project and writes a Markdown summary of every flagged model.

For AI agents the intended loop is draft, check, apply fix, re-check. The deterministic output lets the agent decide whether to rewrite or to surface the violation to a human. The same engine supports three entry points: a CI gate that fails the build, an IDE plugin that annotates the editor, and an in-process call inside a larger orchestration script.

Trade-offs in Adoption

Sqlsure requires an up-to-date semantic model. If the underlying schema changes without corresponding model updates, checks become stale. The library ships no automatic model inference; teams must maintain the JSON or generate it from dbt artifacts.

Coverage is limited to the rule set declared in the model. Novel join patterns or measures not yet tagged will pass silently. The authors report zero false positives on the benchmark set, yet that result holds only for the declared facts.

Performance stays constant regardless of query size because checks are structural. Memory use remains under a few megabytes even on large models. The main cost is the initial model construction, which the project measures in hours for a medium dbt repository rather than days.

Frequently Asked Questions

Does Sqlsure replace query linters? No. It only checks semantic properties such as cardinality and additivity; syntax and style rules remain the domain of tools like SQLFluff.

Can the model be shared across teams? Yes. The JSON file is plain text and can sit in the same repository as the dbt project, so every service consuming the same warehouse sees identical rules.

What happens when a check fails inside an agent loop? The agent receives the fix object, applies the suggested rewrite, and re-submits the query. The loop terminates only when the check returns an empty list.

---

📖 Related articles

Need a consultation?

I help companies and startups build software, automate workflows, and integrate AI. Let's talk.

Get in touch