sqlsure

sqlsure

AI が SQL を作成します。sqlsure が正しさを確認します。

クエリは完全に有効で、エラーなく実行できても、返される数値が気付かないうちに誤っていることがあります。結合による売上の二重計上、合計してしまった平均値、露出した患者識別子などです。データベースではこうした問題を検出できません。リンターでも検出できません。LLM が自分で作成した SQL をレビューしても検出できません。

sqlsure はクエリの実行前に、決定論的に 0.1 ms で検出します。

約束ではなく、証拠を示します： テキストから SQL を生成するモデルの評価に使われる 2 つのベンチマークのゴールド回答を対象に、sqlsure を実行しました。専門家が作成した 2,568 件のクエリで 45 件の警告、誤警告はゼロです。これには、sqlsure が対象とするまさにその種のバグにより、8 倍の誤りが証明されている BIRD の開発用ゴールド回答と、上流に報告済みのスキーマの欠陥も含まれます。

仕組み

sqlsure は、チームがすでに宣言している事実に照らして SQL を判定します。dbt の unique テストは粒度となり、relationships テストは結合カーディナリティとなり、1 行の meta タグで合計しても安全な項目を指定します。新しい言語を覚える必要も、モデルを手動で保守する必要もありません。ルールは LLM の呼び出しではなく、辞書検索です。同じ入力には、常に同じ判定が返されます。オフラインで動作します。

却下のたびに機械が実行できる fix が返されるため、AI エージェントは自動で修正します：下書き → チェック → 修正 → チェック → 実行。 ベンチマークでは、修正をそのまま適用すると、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

3 つの使い方、1 つのエンジン

1. CI ゲート — PR で二重計上が発生した場合、マージをブロックします：

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

2. MCP サーバー — AI エージェントは実行前に検査に合格する必要があります：

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

ツールのリファレンスとエージェントループのパターンについては、docs/MCP.md を参照してください。

3. ライブラリ — check() をテキストから SQL を生成する任意の製品やエージェントフレームワークに組み込めます。すぐに導入できる SemanticGate は、Vanna/WrenAI スタイルのジェネレーターをラップします。セマンティック評価メトリックは、実行精度では検出できない NL2SQL の出力を評価します。

エージェントスキルとしても利用できます — エージェントが直接読み込む単一の SKILL.md です。サーバープロセスは必要ありません。

ルール（v0.1）

ルール	重大度	検出内容
FANOUT	error	1 対多の結合後に加算可能な指標を SUM/COUNT する
CHASM	error	2 つ以上のファンアウト結合が互いに乗算される
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 と同じルールブックなら、常に同じ判定です。ルールは辞書検索で、1 行ずつ監査できます
• オフライン — ネットワーク呼び出しはゼロです。SQL がマシンの外に出ることはありません
• データアクセスなし — クエリの テキスト を解析します。データベースには接続しません
• テレメトリーなし — 収集される情報は一切ありません（SECURITY.md）
• サプライチェーン — リリースは、公開 CI 実行を伴うタグ付きコミットから PyPI Trusted Publishing（OIDC）経由でのみ配布されます。ランタイム依存関係は 2 つです

ルールブックの作成元

• 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 Semantic Views — アダプターはロードマップにあります。エンジンが認識するのは常に 1 つの 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 — 内部の仕組みを、初心者向けから上級者向けまで、実際の中間出力とともに説明します
• 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