QueryPilot

QueryPilot

Safe, measurable SQL for AI agents.

QueryPilot sits between an LLM agent and your database. It gives the agent read-only, policy-checked SQL tools for any SQLAlchemy database. It grounds the model in your real schema, feeds errors back so the model can fix its SQL, and ships an eval harness that proves the SQL is correct and stays correct.

Quickstart

pip install querypilot

querypilot demo

querypilot demo writes a small SaaS database (querypilot-demo.db), runs a validated query against it and shows a blocked DELETE. Then try:

querypilot schema --db sqlite:///querypilot-demo.db              # list tables

querypilot schema --db sqlite:///querypilot-demo.db invoices # columns, keys, sample values querypilot sql --db sqlite:///querypilot-demo.db "SELECT customer_nme FROM customers"

Error: SQL validation failed: Unknown column: customer_nme

hint: Column 'customer_nme' does not exist; did you mean customers.customer_name, ...?

querypilot ask --db sqlite:///querypilot-demo.db "Which customers have the highest ARR?"

ask uses OpenAI or Anthropic when OPENAI_API_KEY or ANTHROPIC_API_KEY is set (--generator openai-compatible covers Ollama, vLLM and LM Studio). Without a key it falls back to an offline demo generator.

For your own database, querypilot init --db postgresql://analyst@db.internal/prod writes a querypilot.yaml that holds the connection, business hints, column descriptions and access policy. Every command, the MCP server and QueryPilot.from_config() read it, so you can drop --db from then on.

In Python:

from querypilot import QueryPilot

qp = QueryPilot.connect("postgresql://analyst@db.internal/prod") # dialect inferred from the URL

result = qp.execute_sql("SELECT plan, COUNT(*) FROM subscriptions GROUP BY plan") print(result.sql) # rewritten with a LIMIT, validated against the live schema print(result.rows)

Connect any database

QueryPilot.connect(url) infers the SQL dialect from the URL and introspects tables, views, primary and foreign keys, and comments. It also accepts a SQLAlchemy Engine.

Every query is validated with sqlglot for the target dialect. Validation means one statement, SELECT only, and known tables and columns. It also blocks dangerous functions for each engine, such as pg_read_file, DuckDB's read_csv, MySQL's LOAD_FILE and SQL Server's xp_cmdshell. Execution then adds the engine's own guard: a read-only transaction on Postgres, MySQL and Oracle, a read-only connection on DuckDB, and a statement timeout where the engine supports one. Every query runs in a transaction that is always rolled back. For warehouses that have no read-only session mode, connect with a read-only role.

Give your agent the tools

Every integration exposes the same small toolset. Results are compact JSON, and errors come back as {"ok": false, "error": ..., "hints": [...]} rather than as exceptions, so the agent can correct itself.

MCP (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf):

querypilot mcp-config claude-code --db postgresql://analyst@db/prod

claude mcp add querypilot --env QUERYPILOT_DATABASE_URL=... -- /path/to/uvx --from 'querypilot[mcp]' querypilot mcp

querypilot mcp-config cursor --db sqlite:///app.db # prints the mcpServers JSON block

The generated config uses the absolute path to uvx, which avoids the common spawn uvx ENOENT failure. Pass --runner python to launch the current environment instead. Every tool carries the MCP readOnlyHint annotation. querypilot mcp --transport streamable-http --port 8000 serves the same tools over HTTP.

OpenAI / Anthropic tool calling:

tools = qp.as_openai_tools()            # Chat Completions; qp.toolkit().openai_responses_tools() for Responses

tools = qp.as_anthropic_tools() result = qp.handle_tool_call(tool_call.name, tool_call.arguments) # dict or JSON string in, dict out

Agent frameworks:

from querypilot.integrations import (

as_langchain_tools, # LangChain / LangGraph StructuredTools as_llamaindex_tools, # LlamaIndex FunctionTools as_openai_agents_tools, # OpenAI Agents SDK FunctionTools as_claude_agent_mcp_server, # Claude Agent SDK in-process MCP server claude_agent_allowed_tools, as_functions, # plain typed functions: Pydantic AI, smolagents, CrewAI, ADK )

tools = as_langchain_tools(qp, naming="langchain") # sql_db_list_tables, sql_db_schema, sql_db_query, ...

naming="langchain" reuses the tool names from the community SQLDatabaseToolkit (no longer maintained), so existing prompts keep working. Install the matching extra: querypilot[langchain], [llamaindex], [openai-agents], [claude-agent] or [mcp]. See examples/07_frameworks.py.

Protect any Postgres client: querypilot proxy (prototype)

The proxy needs no SDK. It is a Postgres wire-protocol server that applies the same validator and access policy to every statement, whatever the client. That covers psql, psycopg, SQLAlchemy and LangChain, an existing MCP database server, Cursor or Claude Code, and BI tools. Point the client's connection string at the proxy instead of the database:

pip install "querypilot[proxy]"

querypilot proxy --upstream postgresql://readonly@db/prod --listen 127.0.0.1:6543 --policy querypilot.yaml

psql "postgresql://agent@127.0.0.1:6543/prod" -c "SELECT email FROM customers" npx -y @modelcontextprotocol/server-postgres postgresql://agent@127.0.0.1:6543/prod # unchanged MCP server

Every statement then gets the following:

• Read-only enforcement. Writes, DDL, COPY and SET of anything outside a small allowlist are rejected. Allowed statements run in a READ ONLY transaction on a session that defaults to read-only, so COMMIT; DROP TABLE … is rejected.
• Row filters and the row cap. The rewritten SQL is what reaches the database, so the policy's row_filters hold under joins, subqueries and CTEs, and LIMIT is capped at max_rows.
• Masking. masking_rules apply by output position, so upper(email) AS contact is masked too.
• Errors an agent can repair. A rejection is a normal Postgres error with a SQLSTATE, the validator's message, and a HINT, for example Column 'nope' does not exist. Columns of orders: id, customer_id, ….
• Audit. One JSONL record per statement goes to --audit-log, with the client's SQL, the SQL that ran, the row count, and the client user and application.

Driver handshakes, SET/SHOW of formatting settings, and catalog queries for psql \d and ORM reflection pass through an allowlist. Catalog queries that could read data, such as pg_stats or query_to_xml(...), are rejected. The policy file is a normal querypilot.yaml, and its database_url is used when you omit --upstream. Off loopback, set QUERYPILOT_PROXY_PASSWORD. Protocol coverage, known gaps (no TLS termination yet, no server-side cursors), and the reasons it fails closed are in docs/proxy.md.

Watch the SQL your agent already runs: querypilot trace and hooks

Some query tools can't sit behind QueryPilot, for example Palantir Foundry's MCP SQL tool. For those, QueryPilot reads what the agent did instead. trace import pairs every query tool call in Claude Code transcripts with its result. hooks install logs new calls live. trace doctor reports the failure rate by class, retry chains, latency and stalls, and says for each problem whether it is best fixed in the tool, the prompt, or the data:

querypilot trace doctor                        # reads ~/.claude/projects

querypilot trace doctor --output report.md # redacted, shareable querypilot hooks install --guard --max-rows 200

With --guard, a PreToolUse hook validates each query against schemas cached from the agent's own schema calls. It denies unknown columns with a "did you mean" reply before the query reaches the warehouse, blocks date arithmetic on DATE columns stored as epoch milliseconds, and enforces a row cap. Foundry's tool is mapped by default; map any other with --tool NAME=SQL_FIELD[:DIALECT]. Recovered retry chains export to eval replay as a regression suite. See docs/trace.md and the first Foundry report.

Better SQL from the model

When QueryPilot writes the SQL itself (ask, ask_database, evals), it uses the techniques with the largest measured gains in the text-to-SQL literature. The sources and numbers are in docs/research/developer-needs.md.

• Grounded schema. The prompt shows each table as compact DDL with primary keys, foreign-key join paths, comments and real values for category-like text columns: every value when there are 10 or fewer, otherwise the 3 most common. Sample values are never drawn from blocked, masked or row-filtered columns.
• Your business rules. Pass hints= and descriptions= to connect(), or set them in querypilot.yaml, for definitions such as "revenue means paid invoices only".
• Pruning only when needed. Below schema_token_budget (default 6000 tokens) the full schema is sent. Above it, QueryPilot sends the relevant tables plus the foreign-key bridge tables that join them.
• A repair loop that converges. Validation errors get "did you mean" hints. Database errors are cleaned before they go back to the model. An empty result triggers one gentle review. Up to 3 attempts by default.

from querypilot import AnthropicSQLGenerator, QueryPilot

qp = QueryPilot.connect( "duckdb:///analytics.duckdb", generator=AnthropicSQLGenerator(), hints=["Revenue means SUM(amount_cents) / 100 over invoices with status = 'paid'"], descriptions={"accounts.segment": "smb, midmarket or enterprise"}, ) answer = qp.ask("Revenue by se