QueryShield › Guides

What is a read-only SQL proxy for AI agents?

Traditional SQL proxies — connection poolers and query routers — forward traffic from applications you wrote and trust. An AI agent is a different kind of client: it writes its own SQL from natural language, and that SQL can be steered by whatever text lands in its context. A read-only SQL proxy for AI is built for that client. Its job is not routing traffic; it is deciding whether each query may run at all.

Read-only user vs. read-only proxy

A read-only database role is the right first layer, and you should keep it. But it enforces one property — no writes — and it has to be configured correctly in every database you connect. On its own it does not stop an agent from:

• reading every row of every table the role can see;
• running an unbounded SELECT that returns millions of rows;
• calling pg_sleep or similar functions that any role can execute, opening a timing side channel;
• holding the connection string itself, where a prompt injection can leak it.

What a read-only SQL proxy enforces

• Structural read-only checks: each query is parsed into an AST. The root must be a SELECT (or a UNION or CTE of SELECTs), and no INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, or MERGE may appear anywhere inside it, including subqueries.
• One statement per call: anything chained after a ; is rejected, and a query the parser cannot resolve is rejected rather than guessed at.
• Function deny-listing: built-ins such as pg_sleep, pg_read_file, dblink, xp_cmdshell, and load_file are refused.
• Bounded results: a LIMIT is required in the SQL, and the proxy applies its own hard row cap on top.
• Per-agent scope: an agent’s policy can restrict it to named schemas and tables and inject a row filter, so read-only also means reading only what that agent should.
• Audit: every allowed and rejected query is written to an append-only log against the agent that sent it.

Read-only database access over MCP

Model Context Protocol clients such as Claude Desktop and Cursor make it easy to hand an agent a database tool — and just as easy to hand it a raw connection string. QueryShield ships as an MCP server (pip install queryshield-mcp) that calls the proxy with a scoped API key, so the MCP client gets read-only, policy-bound database access and never holds the credential.

When a read-only user is enough

For a single trusted analyst agent on a non-sensitive replica, a read-only role with a statement timeout may be all you need. Reach for a read-only SQL proxy when agents take untrusted input, when several agents need different scopes, or when you must prove after the fact what each agent read.

Related guides

• How do I block DELETE and DROP from LLM-generated SQL?
• How do I prevent SQL injection from LLM-generated queries?
• How do I enforce RBAC for AI agents accessing a database?
• How do I stop an AI agent from seeing database credentials?
• How do I give an AI agent safe access to a production database?
• What is a query firewall for AI agents?