Schema-guard verhindert, dass KI-Agenten ungültiges SQL schreiben

KI-Coding-Agenten erzeugen häufig SQL-Abfragen, die auf nicht existierende Tabellen oder Spalten verweisen. Dies führt zu Fehlern in Continuous-Integration-Pipelines oder Produktions-Dashboards. Ein neues Open-Source-Tool namens schema-guard löst dieses Problem, indem es die Ausgabe der Agenten vor der Ausführung gegen einen statischen Snapshot des Datenbank-Schemas validiert. Das Tool wurde im Oktober 2026 veröffentlicht und integriert sich in gängige KI-Assistenten und CI-Systeme, um ungültige Abfragen zu blockieren, während gültige Abfragen ohne Unterbrechung durchlaufen können.

Was passiert ist

Coding-Agenten verlassen sich oft auf veraltete Dokumentationen, wie README-Dateien oder alte Query-Beispiele, um die aktuelle Datenbankstruktur abzuleiten. Dies führt zu "Schema-Halluzinationen", bei denen der Agent Spaltennamen erfindet, die nicht existieren. Snowflake hat dieses Problem in einem Entwickler-Blogbeitrag im September 2026 hervorgehoben und darauf hingewiesen, dass Agenten mit Zugriff auf Code-Repositories, aber ohne Live-Zugriff auf Data-Warehouse-Konten Schwierigkeiten haben, ihre Genauigkeit zu wahren, wenn sich Schemas weiterentwickeln.

Schema-guard löst dies, indem ein leichtgewichtiger Snapshot der Tabellen- und Spaltennamen direkt im Repository gespeichert wird. Dieser Snapshot enthält keine sensiblen Daten oder Zugangsdaten, sondern nur strukturelle Metadaten. Wenn ein KI-Agent versucht, SQL zu schreiben oder auszuführen, prüft das Tool die Abfrage gegen diesen Snapshot. Verweist die Abfrage auf eine fehlende Spalte, lehnt das Tool die Anfrage ab und schlägt korrekte Alternativen vor, z. B. den Ersatz von country durch country_iso2. Der Agent kann dann mit den korrigierten Namen erneut versuchen, was verhindert, dass fehlerhafter Code jemals das Dateisystem oder die Datenbank erreicht.

Das Tool unterstützt mehrere Integrationspunkte, einschließlich Hooks für Claude Code, Model Context Protocol (MCP)-Server für Editoren wie Cursor und VS Code sowie Pre-commit-Hooks für Versionskontrollsysteme. Es bietet auch eine Befehlszeilenschnittstelle für Continuous-Integration-Prüfungen, um sicherzustellen, dass jeder SQL-Code, der im Repository committet wird, dem bekannten Schema entspricht. Dieser mehrschichtige Ansatz stellt sicher, dass sowohl interaktive Agenten-Sitzungen als auch automatisierte Pipelines von derselben Validierungslogik profitieren.

Wie es funktioniert

Schema-guard arbeitet, indem es eine JSON-Datei pflegt, die sich typischerweise unter .schema-guard/schema.json befindet und den aktuellen Zustand der Datenbank darstellt. Entwickler generieren diesen Snapshot über Befehle, die verschiedene Datenquellen verbinden, darunter dbt-Ziele, DuckDB, BigQuery, Snowflake, Databricks oder rohe SQL-Dumps. Der Snapshot erfasst Tabellennamen, Spaltennamen und Datentypen und fasst mehrere Dateien zusammen, wenn das Repository mit mehreren Warehouses interagiert. Nach der Erstellung wird diese Datei im Repository committet, sodass Agenten sie lesen können, ohne direkten Datenbankzugriff zu benötigen.

Wenn ein Agent SQL generiert, parst schema-guard die Abfrage mit sqlglot, einer Bibliothek, die über zwanzig SQL-Dialekte unterstützt. Es löst Common Table Expressions, Subqueries, Aliase und Join-Bedingungen auf, um jede Tabellen- und Spaltenreferenz zu identifizieren. Das Tool vergleicht diese Referenzen anschließend mit dem Snapshot. Fehlt ein Name, berechnet es ähnliche Namen, um Vorschläge anzubieten. Ist die Abfrage gültig, bleibt das Tool still und vermeidet unnötige Unterbrechungen. Dieses Design priorisiert Vertrauen, indem es False Positives minimiert und sicherstellt, dass gültige Abfragen nie aufgrund von Parsing-Ambivalenzen oder nicht unterstützten Funktionen wie dynamischem SQL blockiert werden.

Wichtige Details

• Keine falschen Blockaden: In Benchmarks mit dem Spider-dev-Datensatz produzierte schema-guard null falsche Blockaden bei 1.034 gültigen, menschlich geschriebenen Abfragen über zwanzig Datenbanken hinweg.
• Hohe Korrekturrate: Das Tool fing 1.032 von 1.034 eingebetteten Fehlern ab, bei denen Spaltennamen absichtlich vertauscht oder falsch geschrieben wurden.
• Modellleistung: In Tests mit Claude Haiku 4.5 und Sonnet 5 erhöhte die Nutzung des Schema-Snapshots die Anzahl der ausführbaren SQL-Dateien von null auf zwölf von zwölf Anfragen pro Modell.
• Kosteneffizienz: Die Nutzung der Hook-Integration verursachte vernachlässigbare Kosten; Haiku-Läufe kosteten $0,65 im Vergleich zu $0,58 für die Baseline, während die Kosten für Sonnet identisch bei $1,61 blieben.
• Breite Kompatibilität: Unterstützt Integrationen mit Claude Code, Cursor, VS Code, Windsurf und standardmäßigen CI-Pipelines über Pre-commit-Hooks.
• Sichere Snapshots: Der Schema-Snapshot enthält nur Namen und Typen, schließt alle Zeilendaten und Zugangsdaten aus und ist daher sicher in öffentlichen oder privaten Repositories speicherbar.

Warum es wichtig ist

Für Engineering-Teams, die datenintensive Anwendungen entwickeln, ist Schema-Drift eine ständige Herausforderung. Dokumentationen bleiben selten synchron mit Datenbank-Migrationen, was zu fragilen KI-Interaktionen führt. Schema-guard entkoppelt das Wissen des Agenten von der Live-Datenbank und bietet eine stabile Quelle der Wahrheit, die sich nur entwickelt, wenn Entwickler den Snapshot explizit aktualisieren. Dies reduziert die kognitive Belastung für Entwickler, die zuvor jede generierte Abfrage manuell überprüfen oder obskure "Column-not-found"-Fehler in CI-Logs debuggen mussten.

Das Tool erhöht auch die Sicherheit, indem es die Notwendigkeit des Agenten für direkten Datenbankzugriff einschränkt. Da der Snapshot keine Zugangsdaten enthält, können Agenten effektiv in eingeschränkten Umgebungen arbeiten, wie lokalen Entwicklungsumgebungen oder sicheren CI-Runners. Dies entspricht dem Least-Privilege-Prinzip, reduziert das Risiko versehentlicher Datenoffenlegung oder unbefugter Änderungen und ermöglicht dennoch leistungsstarke Code-Generierungsfunktionen.

Was Sie tun können

• Installieren Sie schema-guard über pip und generieren Sie einen Snapshot für Ihr lokales DuckDB- oder dbt-Projekt, um den Workflow zu testen.
• Fügen Sie den schema-guard-Hook zu Ihrer Claude-Code-Konfiguration hinzu, um Echtzeit-Validierung während interaktiver Coding-Sitzungen zu aktivieren.
• Konfigurieren Sie einen Pre-commit-Hook in Ihrem Repository, um SQL-Dateien automatisch auf Schema-Konsistenz zu prüfen, bevor sie committet werden.
• Aktualisieren Sie Ihre CI-Pipeline, um schema-guard check auf allen SQL-Modellen auszuführen, um sicherzustellen, dass sie dem Schema entsprechen.