Schema-guard、AIエージェントによる無効なSQLの書き込みを防止

AIコーディングエージェントは、存在しないテーブルやカラムを参照するSQLクエリを頻繁に生成し、継続的インテグレーション（CI）パイプラインや本番環境のダッシュボードで失敗を引き起こすことがあります。schema-guardという新しいオープンソースツールは、実行前にデータベーススキーマの静的スナップショットに対してエージェントの出力を検証することでこの問題に対処します。2026年10月にリリースされたこのツールは、人気のあるAIアシスタントやCIシステムと統合され、無効なクエリをブロックしつつ、有効なクエリは中断なく通過させます。

何が起きたか

コーディングエージェントは、READMEファイルや古いクエリの例など、陳腐化したドキュメントに依存して現在のデータベース構造を推測することがよくあります。これにより、「スキーマハルシネーション」と呼ばれる現象が発生し、エージェントが存在しないカラム名を作り出してしまいます。Snowflakeは2026年9月の開発者向けブログ記事でこの問題を指摘し、コードリポジトリへのアクセスはあるもののライブウェアハウスアカウントへのアクセスがないエージェントは、スキーマが進化していく中で精度を維持するのに苦労していることを述べました。

schema-guardは、テーブル名とカラム名の軽量なスナップショットをリポジトリ内に直接保存することでこの問題を解決します。このスナップショットには機密データや認証情報は含まれず、構造メタデータのみが含まれます。AIエージェントがSQLの作成または実行を試みると、ツールはこのスナップショットに対してクエリをチェックします。クエリが存在しないカラムを参照している場合、ツールはリクエストを拒否し、country を country_iso2 に置き換えるといった正しい代替案を提案します。その後、エージェントは修正された名前を使って再試行でき、破損したコードがファイルシステムやデータベースに到達することを防ぎます。

このツールは、Claude Code用のフック、CursorやVS Codeなどのエディタ向けのModel Context Protocol (MCP) サーバー、バージョン管理用のpre-commitフックなど、複数の統合ポイントをサポートしています。また、CIチェックのためのコマンドラインインターフェースも提供しており、リポジトリにコミットされるすべてのSQLが既知のスキーマと一致することを確認します。この多層的なアプローチにより、インタラクティブなエージェントセッションと自動化されたパイプラインの両方が同じ検証ロジックから恩恵を受けることが保証されます。

仕組み

schema-guardは、データベースの現在の状態を表すJSONファイルを .schema-guard/schema.json のような場所に維持することで動作します。開発者は、dbtターゲット、DuckDB、BigQuery、Snowflake、Databricks、または生のSQLダンプなど、さまざまなデータソースに接続するコマンドを使用してこのスナップショットを生成します。スナップショットにはテーブル名、カラム名、データ型がキャプチャされ、リポジトリが複数のウェアハウスとやり取りする場合、複数のファイルがマージされます。一度作成されると、このファイルはリポジトリにコミットされ、エージェントは直接的なデータベースアクセスなしにそれを読み取ることができます。

エージェントがSQLを生成すると、schema-guardはsqlglotライブラリを使用してクエリを解析します。sqlglotは20以上のSQL方言をサポートしています。共通テーブル式（CTE）、サブクエリ、エイリアス、結合条件を解決し、すべてのテーブルおよびカラム参照を特定します。その後、ツールはこれらの参照をスナップショットと比較します。名前が存在しない場合、類似した名前を計算して提案を行います。クエリが有効な場合、ツールは何もしません。これは不要な割り込みを避けるためです。この設計は、パーシングの曖昧性や動的SQLのような未サポート機能によって有効なクエリがブロックされないようにすることで、誤検知を最小限に抑え、信頼性を優先しています。

主要な詳細

• ゼロ誤ブロック: Spider dev データセットを使用したベンチマークでは、schema-guardは20個のデータベースにわたる1,034件の有効な人間作成クエリに対し、誤ブロックをゼロ件で実現しました。
• 高い修正率: カラム名が意図的に入れ替えられたりスペルミスしたりした1,034件の埋め込みエラーのうち、1,032件を検出しました。
• モデルパフォーマンス: Claude Haiku 4.5 と Sonnet 5 を使用したテストでは、スキーマスナップショットの利用により、実行可能なSQLファイル数が各モデルあたり12リクエスト中0件から12件に増加しました。
• コスト効率: フック統合の使用による追加コストは無視できるほど小さく、Haikuの実行コストはベースラインの$0.58に対し$0.65となり、Sonnetのコストは$1.61のまま変化しませんでした。
• 広範な互換性: Claude Code、Cursor、VS Code、Windsurf、およびpre-commitフックを介した標準的なCIパイプラインとの統合をサポートします。
• 安全なスナップショット: スキーマスナップショットには名前と型のみが含まれ、すべての行データと認証情報を除外するため、公開またはプライベートのリポジトリに安全に保存できます。

なぜ重要なのか

データ集約型のアプリケーションを構築するエンジニアリングチームにとって、スキーマドリフトは常に課題です。ドキュメントがデータベースマイグレーションと同期し続けることは稀であり、脆いAIインタラクションにつながります。schema-guardは、エージェントの知識をライブデータベースから分離し、開発者が明示的にスナップショットを更新した場合のみ進化するという安定した信頼できる情報源を提供します。これにより、以前は生成されたすべてのクエリを手動で検証するか、CIログ内の不明瞭な「カラムが見つからない」エラーをデバッグする必要があった開発者の認知的負荷が軽減されます。

このツールは、エージェントが直接的なデータベースアクセスを必要とする要件を制限することによってもセキュリティを強化します。スナップショットには認証情報が含まれていないため、エージェントはローカル開発環境や安全なCIランナーなどの制限された環境内で効果的に動作できます。これは最小権限の原則に沿っており、強力なコード生成機能を可能にしたまま、偶発的なデータ露出や不正な変更のリスクを低減します。

できること

• pip経由でschema-guardをインストールし、ローカルのDuckDBまたはdbtプロジェクトのスナップショットを生成してワークフローをテストしてください。
• インタラクティブなコーディングセッション中のリアルタイム検証を有効にするために、Claude Code設定にschema-guardフックを追加してください。
• リポジトリにpre-commitフックを設定し、SQLファイルがコミットされる前にスキーマ整合性を自動的にチェックしてください。
• CIパイプラインを設定し、すべてのSQLファイルに対して schema-guard check を実行して、コミット前にスキーマとの一貫性を確認してください。
• GitHubリポジトリでissueを開き、フィードバックを提供したり、新機能のリクエストを行ったりしてください。