A SQL agent runs the query itself. That's why production is the hard part.
A SQL agent is a program that takes a natural language question, decides on a SQL query (the text-to-SQL step), runs it against a real database on your behalf, and returns the answer. The agent, not the human, picks the query. That single property is what separates a SQL agent from a sql copilot that only suggests SQL for a human to paste. It is also what makes the trust bar higher: the agent has the credentials, the agent runs the query, and the agent decides what counts as "the answer."
A useful working definition: a SQL agent is read-only execution + credential vault + audit trail + saved and reviewed queries. The first three bound what it can do. The fourth decides what its SQL gets written against. Tools that satisfy the first three but not the fourth are safe and start every question from zero; tools that satisfy the fourth but not the first three are anchored and dangerous. An agent worth pointing at production has all four.
The risk isn't the SQL. It's the blast radius when the model is wrong.
The hard part of building a SQL agent is not the SQL. Models are already competent at writing PostgreSQL for a known schema. Read-only Postgres access for AI is not the hard part either, since a role with no write grants takes an afternoon. The hard part is making the answer trustworthy: an executed query you can read; bounded blast radius if the model goes off the rails; provable record of who ran what, when, against which connection. None of that comes from the model. All of it comes from the surrounding system: the read-only enforcement layer, the credential vault, the audit log, and the saved-query library.
The rest of this page is a checklist of the four properties that, together, make an agent trustworthy enough to point at production. Use it to evaluate any SQL agent: vendor, internal build, or open-source orchestrator.
Score any SQL agent against four production-safety properties.
Each row is a property the agent must demonstrate. Use the checklist to evaluate any SQL agent your team is considering: vendor, internal build, or open source orchestrator. Click any criterion to expand the evaluation questions and how Chion satisfies it.
Local to this page. Use it to score the SQL agent your team is evaluating.
The criteria, in depth
These are ordered. Read-only is first because it is the only one that, if missing, can destroy data. Vault is second because credentials, once leaked, cannot be unleaked. Audit is third because without it nothing else can be proven. Saved and reviewed queries are fourth because the first three bound what the agent may do without deciding what its SQL gets written against.
Criterion01Read-only enforcement lives in code, not model instructions.
The agent cannot write, update, delete, or alter, because the role it connects with has no write grants.
Read-only enforcement lives in code, not model instructions.
The agent cannot write, update, delete, or alter, because the role it connects with has no write grants.
A trustworthy SQL agent treats the database as a read source, not a workspace. Read-only is not a flag the user toggles or a prompt the model is told to obey. It is enforced at three layers: a static SELECT only check before the query leaves the planner, a runtime lint that rejects any DDL or DML token, and a database role that has no write grants at all. Any one of these would stop a destructive query. All three exist so that a bug in any one is still caught.
Evaluate any SQL agent
- ›Can the agent run a query that uses INSERT, UPDATE, DELETE, TRUNCATE, ALTER, or DROP? If yes, fail.
- ›Is read-only enforced by a model instruction, or by code that parses the SQL before it runs? If only the instruction, fail.
- ›Does the underlying database role have any write grants? If yes, fail.
- ›Are unbounded scans rejected and row caps enforced even when the model omits LIMIT? If no, fail.
How Chion satisfies it
Chion uses assertReadOnlySelect at the planner, a runtime lint inside the executor, and a Postgres role with no write grants. Caps: 1,000 rows, 12,000 cells, LIMIT auto enforced via ensureTopLimit. A query that violates any of the three is rejected before it touches the connection.
Criterion02Credential vault, not credential paste
The agent never sees, stores, or logs raw database credentials.
Credential vault, not credential paste
The agent never sees, stores, or logs raw database credentials.
A read-only SQL agent must be able to query a real warehouse without becoming a credential exfiltration risk. That means credentials live encrypted at rest, are decrypted only at the moment of use, and are wiped from memory immediately after. The model itself never receives the DSN, the password, or the connection string. It receives a session handle. If the session is logged or leaked, it expires before it is useful. This is the difference between an LLM SQL tool that asks the user to paste a password into chat and a Postgres AI agent built for production.
Evaluate any SQL agent
- ›Are credentials encrypted at rest with a per-tenant key (AES 256 GCM or better)?
- ›Are credentials decrypted only inside a server side function with a short TTL and a hard read cap?
- ›Does the language model ever receive the raw DSN or password in a prompt? If yes, fail.
- ›Which credential events reach the audit table, and which code paths skip the audit call?
How Chion satisfies it
Chion resolves credentials via resolveConnectionVault and resolveSourceVault only. Storage is AES 256 GCM. Decrypted material has a 60 second TTL and a maximum of 5 reads, after which it is consumed and purged. The model receives a session reference, never the connection string. Decrypt and purge events have named audit types (credential.decrypted, credential.purged), and coverage is not yet uniform: some consume and purge paths run without an audit callback, so treat the trail as strong on decrypt and incomplete on teardown.
Criterion03An audit row for every executed query
Every executed query leaves a row naming the user, the connection, and the result size.
An audit row for every executed query
Every executed query leaves a row naming the user, the connection, and the result size.
If the agent cannot answer "what did this user run, when, against which connection, and what was the row count," then it is not auditable. A trustworthy SQL agent treats the audit trail as a first class output of every run, not a debug log. Ask what the row actually holds, too: a trail that stores the raw prompt and the rendered SQL has copied whatever sat in that text into a second table, which is a data-handling decision, not a free win. The point is that security review will ask, and the answer "we trust the model" will not pass.
Evaluate any SQL agent
- ›Is there a single table that records every query the agent ran?
- ›What identifies the query in that row: a hash, or the full SQL and prompt text? Who can read the table?
- ›Can the agent itself write to or read from the audit log? If yes, fail.
- ›Is the audit log retained long enough for security review to use it (90 days minimum)?
How Chion satisfies it
Chion edge functions in the SQL path write a security_audit_log row per executed query: event type, user id, connection id, source id, request id, a SHA-256 query hash, the mode, and the row count. The prompt text and the rendered SQL are not columns in that table, so the audit trail identifies a query without duplicating what it selected. The table is writable only by service role functions. The write is fire-and-forget, so it never blocks or fails the query response, and a failed insert is logged rather than retried.
Criterion04Saved and reviewed SQL anchors what the model is allowed to generate
Each question produces a new SELECT, written on top of a query a person already saved and reviewed.
Saved and reviewed SQL anchors what the model is allowed to generate
Each question produces a new SELECT, written on top of a query a person already saved and reviewed.
This is the property that separates a saved-query workflow from a generic LLM SQL wrapper. Every question runs the pipeline: schema parse, intent, joins, synthesis, validation. What changes once a person reviews a query and saves it in Studio is the starting point. The saved and reviewed SQL becomes the base the next generation is written against, so a follow-up question filters or aggregates over reviewed logic instead of re-deriving the joins from the raw schema. That claim is narrower than determinism, deliberately. The model still writes new SQL on every turn, which is why the executed SELECT is shown with the result.
Evaluate any SQL agent
- ›Can a reviewed query be saved as a reusable artifact your team owns?
- ›Is a repeat question anchored on that saved and reviewed SQL, or re-derived from the schema every time?
- ›Is the artifact human readable, diff-able, and reviewable in pull requests?
- ›When a column is renamed, does the artifact fail loudly instead of silently emitting old SQL?
How Chion satisfies it
Queries saved and reviewed in Chion Studio become the base CTE that later generation is wrapped around (wrapWithBase, in the discovery and SQL pipeline). Every turn still generates a new SELECT, and that SELECT still passes both validators before execution. Skills compiled from saved and reviewed SQL are portable files the team owns, and they break loudly on column drift. For the file format itself, see the Claude Code Skills guide.
Antipatterns: what an untrustworthy agent looks like
Each of these is a real shape of agent we have seen ship. None of them are hypothetical. If the agent you are evaluating matches any row below, the checklist above is not satisfied.
Service account with full DDL
The agent connects with a role that can also DROP TABLE. The model has never been asked to drop a table, but the next jailbreak is one prompt away.
Credentials pasted into prompt
The DSN ends up in the conversation history, the model provider logs, the training set, and the support ticket attached to last week's bug report. Rotate everything.
No audit table at all
Application logs are not an audit trail. They rotate, they get sampled, they are written by the model. Security review will ask for one audit row per query, written by a service role. There is none.
Nothing to anchor generation on
The agent has no saved and reviewed query to build on, so every question is re-derived from the raw schema. Tuesday's joins and Wednesday's joins come out different, and nobody can point at the version a reviewer signed off on.
Read-only enforced only by prompt
"You are a helpful read only sql agent" is not an enforcement mechanism. It is a polite request the model can override the moment an attacker asks it to.
Unbounded queries
No LIMIT, no row cap, no cell cap. The first "show me all transactions" pulls 80 million rows and the connection times out for everyone else on the warehouse.
How Chion satisfies the checklist
Each criterion maps to a specific subsystem, not a marketing claim.
Every row in the checklist maps to a specific Chion subsystem, not a marketing claim. The table below is a one line answer per row; the depth section above carries the detail.
| Criterion | Chion implementation |
|---|---|
| Read-only | assertReadOnlySelect + runtime lint + no-write Postgres role; LIMIT auto enforced. |
| Credential vault | AES 256 GCM at rest; 60s TTL, 5 read cap, consume + purge; model receives session handle only. |
| Audit trail | security_audit_log: event type, user, connection, source, request id, SHA-256 query hash, rows. No prompt or SQL text. Service role writes only. |
| Saved queries | SKILL.md bundles with YAML frontmatter + code-validated SELECT; saved and reviewed SQL becomes the base CTE later generation wraps around. |
For the underlying security posture in detail, see Trust and Security. For the analyst role on top of this agent, see AI SQL analyst. For where this fits in a broader operating model, see AI SQL workforce. For the saved-query skill format, see the Claude Code Skills guide, and for how queries compile into skills, see how Chion builds them.
Walk the four properties in order. Any failure is disqualifying for production.
When evaluating a SQL agent, walk the four criteria in order and treat any failure as disqualifying. Read-only is non-negotiable: an agent that can issue DDL or DML, even "rarely," is a write-capable agent. Credential vault is non-negotiable: any path where the raw DSN reaches the model (prompt, tool input, conversation history) leaks it. Audit trail is non-negotiable: if the agent cannot answer who ran what query when, security review will not sign off. Saved and reviewed queries are non-negotiable for any team that needs a repeat question answered against logic somebody already reviewed.
Beyond the four, two more questions are worth asking. Does the agent expose its skills as portable files (SKILL.md or equivalent) that your team owns and can review in pull requests? And does the agent's vendor publish the underlying security posture (encryption, role grants, retention) in plain language? Chion's posture lives at Trust and Security. The single-agent role built on top is the analyst product page; the team-scale framing is the AI SQL workforce.
Quick reference
- A SQL agent runs queries on your behalf. The trust bar is higher than for a copilot.
- Read-only must be enforced in code at three layers, not in the prompt.
- Credentials live in an encrypted vault; the model never sees the DSN.
- Each executed query writes one audit row, fire-and-forget by design, by service role only: event type, user, connection, a SHA-256 query hash, and the row count. Not the prompt, not the SQL text.
- Saved and reviewed queries are what a new SELECT gets written against, so a repeat question is not re-derived from the raw schema.
- SQL skills for AI agents are portable SKILL.md bundles teams own and review.
Frequently asked
Are sql agents safe to run against production?
Only if four properties hold: read-only enforced in the code path rather than in the prompt, credentials in an encrypted vault the model never touches, an audit row written per executed query, and saved and reviewed queries the team owns for later generation to build on. An agent missing any one of those is a demo with production permissions.
What is a sql agent, in one sentence?
A sql agent is a program that takes a natural language question, decides on a SQL query to run on your behalf against a database, executes it, and returns the answer, typically with some level of autonomy over which query to write.
Is a SQL agent the same as Microsoft SQL Server Agent?
No. SQL Server Agent is Microsoft's job scheduler for SQL Server. An AI SQL agent answers questions by running SQL, and this post covers the AI kind.
What makes a sql agent trustworthy?
It generates SQL a person can check, and it anchors that generation on SQL a person already saved and reviewed. In Chion the first run goes through the full pipeline and produces a SELECT you can read. Once you save that query in Studio, later generation is wrapped around it as a base CTE, so the next question builds on reviewed logic rather than re-deriving the joins. The model still writes the outer SELECT each time, and both validators still run before execution.
How does Chion stop a postgres ai agent from running destructive queries?
Three layers. A static SELECT only check rejects any non-SELECT before the query is queued. A runtime lint inside the executor rejects DDL and DML tokens. The underlying Postgres role has no write grants. A destructive query has to defeat all three to land, and any one of them stops it on its own.
Does the model see my database password?
No. Chion encrypts credentials with AES 256 GCM at rest. They are decrypted only inside a server side credential vault, with a 60 second TTL and a maximum of 5 reads, after which the decrypted material is purged. The language model receives a session reference, never the raw DSN or password.
What is in the audit trail?
For every query the agent runs: the event type, the user, the connection id, the source id, the request id, a SHA-256 hash of the query text, the mode, and the row count. The prompt and the rendered SQL are deliberately not columns, so the trail identifies a query without copying what it selected into a second table. Writes go through service role functions only; the agent has no read or write access.
Are sql skills for ai agents portable across tools?
Yes. A Chion skill is a SKILL.md file: YAML frontmatter plus a saved and reviewed SELECT. The same file can be checked into a repo, reviewed in a pull request, and read by any agent that understands the format, including Claude Code, OpenAI agents, and custom orchestrators.
What is the difference between a sql agent and a sql copilot?
A copilot suggests SQL for a human to run. An agent runs the SQL itself. The trust bar is therefore higher for an agent: read-only enforcement, credential vault, audit trail, and saved and reviewed queries to build on are all properties a copilot can skip but an agent cannot.
Run a SQL agent your security team will sign off on.
Read-only SELECT. Credentials in an AES-256-GCM vault. Results capped at 1,000 rows. Each executed query leaves an audit row, written fire-and-forget so a logging failure never blocks your answer. Saved and reviewed queries compile into portable SQL skills you own.