Databases

db_query & Data Browse

Sometimes the agent needs to see real data to help — the actual shape of a row, a sample record, a count. The db_query tool lets it run read-only queries against a database you connected, but only if you explicitly turn it on for that connection.

ToggleAllow AI queriesDefaultOFFEnginesPostgres · MySQL · SQLite · MongoDB

Turning it on

In the Database panel, each connection has an Allow AI queries toggle — “Let the AI assistant run read-only queries against this connection.” It is off by default. Flip it on per connection when you want the agent to read from that database.

Real rows go to your model provider

The whole point of this feature is sending actual rows to the LLM. Read-only protects the database, not against what’s read leaving your machine. Prefer a non-production connection, and only enable it on data you’re comfortable sharing with your model provider.

How the agent uses it

Once enabled, you just ask — for example “show me a few rows from the orders table so we get the column names right.” The agent issues a db_query and the result renders in a read tool-card, marked as a read-only, rolled-back transaction:

db_query result

postgres · shop_dev  (read-only transaction, rolled back)columns: id, email, status, created_atrows (showing 3 of 4123)  1  ada@example.com   active   2026-05-01  2  grace@example.com paused   2026-05-02  3  linus@example.com active   2026-05-03

What keeps it safe

Connection-level read-only — queries run inside a read-only transaction that is always rolled back. This is the primary control, not just a keyword filter.
Statement allowlist — only SELECT, WITH…SELECT, SHOW, and EXPLAIN are accepted; writes and DDL are rejected up front.
Row cap — results are capped (default 50, hard max 1000), with a truncation marker and the true count.
Per-query timeout and result-size clipping.
No credentials to the agent — the tool references a connection by engine id and relays through the DB extension; it never sees your connection secrets.

Royal mode can't bypass the opt-in

The consent check lives inside the database extension that owns the credentials, reached only across an extension boundary. The agent’s mode is invisible there — so even Royal mode cannot auto-enable AI queries. If the toggle is off, the query is refused.

Engine support

db_query works against all four engines — PostgreSQL, MySQL, SQLite, and MongoDB. The SQL engines take a query written as SQL text; MongoDB instead takes a JSON-stringified query spec ({"collection":"users","filter":{"active":true},"limit":20}). MongoDB has no engine-level read-only transaction to roll back, so its read-only guarantee is structural instead: only find runs — no $out/$merge/aggregation side effects, and no update operators ($set, $inc, …) are accepted anywhere in the filter, including nested inside $and/$or.