Schema-guard prevents AI agents from writing invalid SQL

AI coding agents frequently generate SQL queries that reference non-existent tables or columns, causing failures in continuous integration pipelines or production dashboards. A new open-source tool called schema-guard addresses this by validating agent output against a static snapshot of the database schema before execution. Released in October 2026, the tool integrates with popular AI assistants and CI systems to block invalid queries while allowing valid ones to pass without interruption.

What happened

Coding agents often rely on outdated documentation, such as README files or old query examples, to infer the current database structure. This leads to "schema hallucination," where the agent invents column names that do not exist. Snowflake highlighted this issue in a September 2026 developer blog post, noting that agents with access to code repositories but not live warehouse accounts struggle to maintain accuracy as schemas evolve.

Schema-guard solves this by storing a lightweight snapshot of table and column names directly in the repository. This snapshot contains no sensitive data or credentials, only structural metadata. When an AI agent attempts to write or execute SQL, the tool checks the query against this snapshot. If the query references a missing column, the tool denies the request and suggests correct alternatives, such as replacing country with country_iso2. The agent can then retry with the corrected names, preventing broken code from ever reaching the file system or database.

The tool supports multiple integration points, including hooks for Claude Code, Model Context Protocol (MCP) servers for editors like Cursor and VS Code, and pre-commit hooks for version control. It also provides a command-line interface for continuous integration checks, ensuring that any SQL committed to the repository matches the known schema. This multi-layered approach ensures that both interactive agent sessions and automated pipelines benefit from the same validation logic.

How it works

Schema-guard operates by maintaining a JSON file, typically located at .schema-guard/schema.json, which represents the current state of the database. Developers generate this snapshot using commands that connect to various data sources, including dbt targets, DuckDB, BigQuery, Snowflake, Databricks, or raw SQL dumps. The snapshot captures table names, column names, and data types, merging multiple files if the repository interacts with several warehouses. Once created, this file is committed to the repository, allowing agents to read it without needing direct database access.

When an agent generates SQL, schema-guard parses the query using sqlglot, a library that supports over twenty SQL dialects. It resolves common table expressions, subqueries, aliases, and join conditions to identify every table and column reference. The tool then compares these references against the snapshot. If a name is missing, it calculates similar names to offer suggestions. If the query is valid, the tool remains silent, avoiding unnecessary interruptions. This design prioritizes trust by minimizing false positives, ensuring that valid queries are never blocked due to parsing ambiguities or unsupported features like dynamic SQL.

Key details

• Zero false blocks: In benchmarks using the Spider dev dataset, schema-guard produced zero false blocks on 1,034 valid human-written queries across twenty databases.
• High correction rate: The tool caught 1,032 out of 1,034 planted errors where column names were intentionally swapped or misspelled.
• Model performance: In tests with Claude Haiku 4.5 and Sonnet 5, using the schema snapshot increased the number of runnable SQL files from zero to twelve out of twelve requests per model.
• Cost efficiency: Using the hook integration added negligible cost, with Haiku runs costing $0.65 compared to $0.58 for the baseline, and Sonnet costs remaining identical at $1.61.
• Broad compatibility: Supports integrations with Claude Code, Cursor, VS Code, Windsurf, and standard CI pipelines via pre-commit hooks.
• Safe snapshots: The schema snapshot includes only names and types, excluding all row data and credentials, making it safe to store in public or private repositories.

Why it matters

For engineering teams building data-intensive applications, schema drift is a constant challenge. Documentation rarely stays in sync with database migrations, leading to fragile AI interactions. Schema-guard decouples the agent's knowledge from the live database, providing a stable source of truth that evolves only when developers explicitly update the snapshot. This reduces the cognitive load on developers who previously had to manually verify every generated query or debug obscure column-not-found errors in CI logs.

The tool also enhances security by limiting the agent's need for direct database access. Since the snapshot contains no credentials, agents can operate effectively within restricted environments, such as local development setups or secure CI runners. This aligns with least-privilege principles, reducing the risk of accidental data exposure or unauthorized modifications while still enabling powerful code generation capabilities.

What you can do

• Install schema-guard via pip and generate a snapshot for your local DuckDB or dbt project to test the workflow.
• Add the schema-guard hook to your Claude Code configuration to enable real-time validation during interactive coding sessions.
• Configure a pre-commit hook in your repository to automatically check SQL files for schema consistency before they are committed.
• Update your CI pipeline to run schema-guard check on all SQL models, ensuring that merged code always matches the current schema snapshot.
• Review the generated .schema-guard/schema.json file to understand what metadata is captured and ensure it aligns with your team's privacy policies.
• Contribute to the project by reporting false blocks or adding support for additional database dialects through the GitHub repository.