Show HN: Sqlsure – AI生成SQLの決定論的セマンティックチェック
Show HN: Sqlsure – deterministic semantic checks for AI-generated SQL (github.com)
要約
Sqlsureは、AIが生成したSQLクエリに対して、実行前に決定論的なセマンティックチェックを行うツールです。データベースやリンターが見逃すような、論理的な誤り(例:二重計上、誤った集計)を検出します。dbtテストやスキーマ定義などの既存の事実に基づいてルールを定義し、高速かつオフラインで動作します。
全文翻訳
sqlsure
[画像: CI] [画像: PyPI] [画像: License: Apache-2.0] [画像: Python]
AIがSQLを生成し、sqlsureがその正しさを保証します。
クエリは完全に有効で、エラーなく実行され、静かに間違った数値を返すことがあります — 例えば、結合によって収益が二重計上されたり、平均値が集計されたり、患者識別子が公開されたりします。データベースはこれを検出しません。リンターも検出しません。自身のSQLをレビューするLLMも検出しません。
sqlsureはこれを検出します — 決定論的に、0.1msで、クエリが実行される前に。
約束ではなく、証明: 私たちは、すべてのテキスト・トゥ・SQLモデルが評価される2つのベンチマークのゴールドアンサーに対してsqlsureを実行しました。2,568件の専門家が書いたクエリ、45件のフラグ、偽陽性ゼロ — これには、sqlsureがターゲットとするバグクラスによって8倍も間違っていることが証明されているBIRD devのゴールドアンサーや、すでにアップストリームに提出されたスキーマの欠陥も含まれます。
仕組み
sqlsureは、チームがすでに宣言した事実(dbtのuniqueテストは粒度として、relationshipsテストは結合カーディナリティとして、1行のmetaタグは集計しても安全なものをマークする)に対してSQLを評価します。学習すべき新しい言語はなく、手動でメンテナンスするモデルもありません。ルールは辞書ルックアップであり、LLM呼び出しではありません — 同じ入力、同じ判定、常に、オフラインで実行されます。
すべての拒否には機械が解釈可能なfixが付随するため、AIエージェントは自己修復します:ドラフト → チェック → 修正 → チェック → 実行。 私たちのベンチマークでは、修正をそのまま適用することで、10/10回パスするクエリが生成されました。
クイックスタート
pip install sqlsure
from sqlsure import SemanticModel, check
violations = check(sql, model) # [] は意味的に安全であることを意味します
または、クローンして30秒のデモを実行してください:
python check.py # 5件の間違ったクエリが拒否され、1件が承認されました — 修正付き
python -m sqlsure.scan path/to/dbt-repo --report report.md # 任意のdbtリポジトリを監査します
3つのドア、1つのエンジン
1. CIゲート — PRが二重計上した場合、マージをブロックします:
python -m sqlsure.cli --model model.json query.sql # 違反があった場合に終了コード1を返します
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スタイルのジェネレーターをラップし、semantic eval metricは実行精度が不明なNL2SQL出力をスコアリングします。
Agent Skillとしても利用可能 — エージェントが直接ロードする単一の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 + 同じルールブック = 同じ判定、常に。ルールは辞書ルックアップであり、行ごとに監査可能です。
- オフライン — ネットワーク呼び出しゼロ。あなたの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→ grain、リレーションシップjoinType+condition→ join edges、キューブメジャー → 加算性。 -
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 — 物理的にどのように機能するか、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