sqlsure

sqlsure

AI 编写 SQL，sqlsure 确保它正确无误。

一个查询可能完全有效、运行时没有错误，却悄无声息地返回错误数字——连接导致收入被重复计数、平均值被求和、患者标识符遭到暴露。数据库发现不了这些问题。代码检查工具发现不了这些问题。让 LLM 检查自己编写的 SQL 也发现不了这些问题。

sqlsure 可以——以确定性的方式，在 0.1 ms 内、查询运行之前完成检查。

**证据胜于承诺：**我们用 sqlsure 检查了文本转 SQL 模型普遍采用的两个基准测试的标准答案。2,568 条专家编写的查询，发现 45 个问题，零误报——其中包括一条 BIRD 开发集标准答案，它因 sqlsure 针对的确切错误类型而被证实错了 8 倍；此外还有一个已向上游提交的问题，涉及模式缺陷。

工作原理

sqlsure 根据团队已经声明的事实检查 SQL——dbt 的 unique 测试定义粒度，relationships 测试定义连接基数，一行 meta 标签就能标记哪些内容可以安全求和。无需学习新语言，也无需手动维护模型。规则通过字典查找，而非调用 LLM：相同输入、相同结论，每次如此，且可离线运行。

每次拒绝都会附带可由机器执行的 fix，让 AI Agent 自动修复：**起草 → 检查 → 修复 → 再检查 → 执行。**在我们的基准测试中，原样应用修复后，查询 10 次中有 10 次通过。

快速开始

pip install sqlsure

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

或者克隆并运行 30 秒演示：

python check.py                   # 5 wrong queries rejected, 1 approved — with fixes
python -m sqlsure.scan path/to/dbt-repo --report report.md   # audit any dbt repo

三种接入方式，一个引擎

1. CI 门禁 — 当 PR 中的查询导致重复计数时，阻止合并：

python -m sqlsure.cli --model model.json query.sql   # exit 1 on violations

2. MCP 服务 — AI Agent 必须通过检查才能执行查询：

claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json

工具参考和 Agent 循环模式请参阅 docs/MCP.md。

3. 库 — 在任何文本转 SQL 产品或 Agent 框架中嵌入 check()。可直接替换的 SemanticGate 可包装 Vanna/WrenAI 风格的生成器；语义评估指标 可为 NL2SQL 输出评分，弥补执行准确率无法识别的问题。

还可用作 Agent Skill — Agent 可直接加载的单个 SKILL.md；无需服务器进程。

规则（v0.1）

规则	严重级别	可捕获的问题
FANOUT	error	一对多连接后对可加度量执行 SUM/COUNT
CHASM	error	两个或更多扇出连接相互叠加
ADDITIVITY	error	对不可加度量（比率、平均值）执行 SUM
SEMI_ADDITIVE	error	沿快照维度对余额/普查数据求和
JOIN_KEY	error	使用与任何已声明关系均不匹配的列进行连接
CROSS_JOIN	error	没有谓词的连接
WEIGHTED_AVG	warning	扇出导致 AVG 被悄然重新加权
UNDECLARED_JOIN	warning	没有已声明关系的连接（无法验证 ≠ 安全）
SENSITIVE_COLUMN	policy	查询输出中暴露 PHI/PII 列

如果 sqlsure 无法验证某项内容，它会说明“无法验证”，绝不会说“看起来没问题”。诚实地表达不确定性是一项特性。

信任属性

• 确定性 — 相同 SQL + 相同规则手册 = 始终得到相同结论；规则通过字典查找实现，可逐行审计
• 离线运行 — 零网络调用；你的 SQL 永远不会离开你的设备
• 不访问数据 — 解析查询文本；绝不连接数据库
• 无遥测 — 永不收集任何信息（SECURITY.md）
• 供应链 — 发布仅通过 PyPI Trusted Publishing（OIDC）从带标签的提交进行，并附带公开的 CI 运行；仅有两个运行时依赖

规则手册的来源

• dbt（目前可用）：manifest.json 或 schema.yml——团队已编写的测试会成为可强制执行的语义，无需配置

• 纯 PK/FK 声明（目前可用——为基准测试审计提供支持）

• 实时数据库本身（目前可用）：完全没有语义层？sqlsure.introspect 会从目录构建规则手册——SQLite PRAGMA 或 information_schema PK/FK（postgres/mysql）。检查 BIRD 自己的数据库文件，找回了基准测试已发布架构中缺失的 2 个外键 （bird-bench/mini_dev#37）

  from sqlsure.introspect import model_from_sqlite
  model = model_from_sqlite("app.db")   # PK -> grain, FK -> join edges
  

• 手写 JSON——model.example.json

• OSI 和 WrenAI MDL（可用的加载器位于 integrations/）：OSI 已通过规范中发布的示例进行演示； WrenAI MDL 已通过 WrenAI 自带的 示例清单进行演示——primaryKey → 粒度，关系的 joinType + condition → 联接边，立方体度量 → 可加性

• Cube、Snowflake 语义视图——适配器已列入路线图；引擎始终只接收一个 SemanticModel

验证结果

• 配对基准测试中 16/16 条规则测试，召回率 100% / 误报率 0% （docs/METRICS.md）
• 真实生产代码库（Mattermost 的数据仓库、Fivetran 包、 dbt 的 jaffle shop）——docs/TEST-REPORTS.md
• Spider + BIRD 黄金查询——上文所述的零噪声外部审计

了解更多

• docs/EVIDENCE.md——它能为你做什么，每项 声明都链接到可重新运行的测量结果
• docs/ARCHITECTURE.md——它在底层如何工作， 从 ELI5 到专家级，包含真实的中间输出
• docs/FOR-DUMMIES.md——从零开始介绍所有概念
• docs/INTEGRATIONS.md——GitHub Action、pre-commit、 MCP、Snowflake UDF / Cortex Agent 工具、查询历史审计
• docs/MCP.md——MCP 服务文档
• CONTRIBUTING.md——添加规则和加载器

Apache-2.0 · sqlsure.ai

mcp-name: io.github.sqlsure/sqlsure