What a SQL agent is
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 + verified skills. The first three keep it safe. The fourth keeps its answers stable across runs. Tools that satisfy the first three but not the fourth are safe-but-flaky; tools that satisfy the fourth but not the first three are stable-but-dangerous. A verified sql agent is all four.
Why trust is the hard part
The hard part of building a sql agent is not the SQL. Models are already competent at writing PostgreSQL for a known schema. The hard part is making the answer trustworthy: identical question, identical SQL; 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 verified-skill registry.
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.
The four criteria, at a glance
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. Verified skills are fourth because without them every other guarantee still leaves answers that drift run to run.
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 parse 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.
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 a single append-only row per query. There is none.
Every prompt re-synthesizes SQL
The agent has no concept of a saved skill. The same question on Tuesday and Wednesday produces different SQL because the model is non-deterministic. Numbers drift week over week.
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: prompt, SQL, user, connection, rows, latency — append only, server side only. |
| Verified skills | SKILL.md bundles with YAML frontmatter + validated SELECT; re-asks short circuit to the registry. |
For the underlying security posture in detail, see Trust and Security. For the analyst persona on top of this agent, see SQL AI analyst. For where this fits in a broader operating model, see AI SQL workforce. For the verified-skill file format, see the Claude Code Skills guide, and for how queries compile into skills, see how Chion builds them.
Choosing a SQL agent
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. Verified skills are non-negotiable for any team that needs the same question to return the same number two weeks in a row.
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 persona built on top is the SQL AI analyst; 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.
- Every query writes one row to an append only audit table — prompt, SQL, user, rows, latency.
- Verified sql skills are how a verified sql agent stops re-hallucinating the same SQL on every prompt.
- Sql skills for ai agents are portable SKILL.md bundles teams own and review.
Frequently asked
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.
What makes a sql agent "verified"?
A verified sql agent does not re-synthesize the same query on every prompt. The first run goes through the full pipeline and is reviewed by a human. The validated SQL is promoted to a verified sql skill (a SKILL.md the team owns) and the next matching prompt routes to that skill instead of asking the model again. Same question, same SQL, every time.
How does Chion stop a postgres ai agent from running destructive queries?
Three layers. A static SELECT only parse 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 prompt, the rendered SQL, the user, the connection id, the row count, the latency, and the outcome. The table is append only and writable only by server side functions. The agent itself has no write or read access to it.
Are sql skills for ai agents portable across tools?
Yes. A Chion skill is a SKILL.md file: YAML frontmatter plus a verified 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 verified skills are all properties a copilot can skip but an agent cannot.
Are sql agents safe to run against production?
Only if four properties hold: read only enforced in code (not just the prompt), credentials in an encrypted vault the model never touches, every query written to an append only audit table, and verified sql skills the team owns so re-asks do not re-hallucinate. An agent missing any one of those is a demo with production permissions, not a verified sql agent.
Run a sql agent your security team will sign off on.
Read only by construction, vault backed credentials, full audit trail, and verified sql skills your team owns.