Run a database query
db_queryRun one read-only statement against PostgreSQL, MySQL, SQLite, MongoDB, or Redis, inferring the engine from the connection; writes stay refused until explicitly enabled.
Instructions
Run one statement against one database (PostgreSQL, MySQL/MariaDB, SQLite, MongoDB or Redis, inferred from the connection). READ-ONLY BY DEFAULT: writes are refused unless "readOnly" is false, and statements that change schema or privileges additionally require "allowDestructive" to be true. Call db_list and db_schema first so table and column names are not guessed, and prefer "params" over inlining values in "query" so the values never appear in the statement text. Put a LIMIT in every query: results are capped anyway, and a cap you did not ask for is how a table gets silently half-read. MongoDB: "collection" is required and "action" picks the operation -- find, count, distinct, aggregate and explain read; insert, update, updateOne, replace, delete and deleteOne write and need "readOnly": false. Prefer the *One actions: one document, not every match. Redis: "query" is a single command such as GET or SCAN.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | Connection string, for example postgres://user@host/db, mysql://user@host/db, sqlite:///path/to/app.db, mongodb://host/db or redis://host. Pass "profile" wherever db_list shows one. | |
| sort | No | MongoDB only, action "find". Sort document as JSON, for example {"createdAt":-1}. | |
| field | No | MongoDB only, action "distinct". The field whose distinct values are wanted. | |
| limit | No | MongoDB only. Documents to return, at most 1000; defaults to 50. | |
| query | Yes | One statement only: SQL, a MongoDB filter (JSON object), a MongoDB aggregation pipeline (JSON array), or a single Redis command. Multiple statements separated by ";" are refused. | |
| action | No | MongoDB only. Reads: find (default), count, distinct, aggregate, explain. Writes: insert, update, updateOne, replace, delete, deleteOne, which need "readOnly": false. "explain" returns the planner output and never runs it. The *One actions touch one document and accept an empty filter; the plural ones refuse one, because there it means the whole collection. | find |
| cursor | No | MongoDB only. An opaque resume token from a previous result's "nextCursor". Not used by PostgreSQL, MySQL, SQLite or Redis. | |
| format | No | How rows are rendered as text. "json" is an array of objects; "jsonl" is one object per line and cheapest for many wide rows; "csv", "tsv" and "markdown" are tables. | json |
| offset | No | MongoDB only. Documents to skip, for pagination. Not used by PostgreSQL, MySQL, SQLite or Redis -- put an OFFSET or a keyset predicate in "query" for those. | |
| params | No | Values bound to placeholders in "query" instead of pasted into it: ? for MySQL and SQLite, $n for PostgreSQL. Prefer this: a bound value never reaches the statement text, the log, or a plan cache. SQL only. | |
| update | No | MongoDB only, action "update" or "updateOne". The update document as JSON, for example {"$set":{"seen":true}}. "update" applies it to every match, "updateOne" to the first. | |
| upsert | No | MongoDB only, action "update", "updateOne" or "replace". Insert when nothing matches. | |
| maxRows | No | Rows to return at most (default 1000, ceiling 1000000). The response says whether anything was dropped. | |
| profile | No | A profile name from db_list. Exactly one of "profile" (a name from db_list) or "uri" (an ad-hoc connection string). Prefer "profile": it keeps the password out of the transcript. | |
| timeout | No | Milliseconds before giving up on the statement (default 30000, between 1 and 86400000). | |
| document | No | MongoDB only, action "replace". The replacement document as JSON, for example {"name":"x"}. It replaces the matched document whole, so fields it omits are gone. | |
| maxBytes | No | Bytes of result to return at most (default 262144, ceiling 67108864). | |
| readOnly | No | True (the default) allows only reads. False permits writes to existing data. | |
| collection | No | MongoDB only. Required for every MongoDB action. | |
| projection | No | MongoDB only, action "find". Fields to return as JSON, for example {"name":1,"email":1}. | |
| allowDestructive | No | The second gate. With "readOnly": false, required for schema and grant changes (CREATE, ALTER, DROP, TRUNCATE, GRANT, REVOKE) and for MongoDB $out/$merge. Two flags from one caller is a weak boundary; the control that holds is a database role without those privileges. | |
| allowWriteStages | No | MongoDB only, action "aggregate". Permit $out and $merge, which replace a collection. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | False when the call failed; read "error" then. | |
| hint | No | ||
| rows | Yes | The result. Null if a result limit dropped it. | |
| bytes | Yes | ||
| error | No | Present only when "ok" is false. | |
| driver | No | ||
| format | Yes | Rendering used for the text content block. | |
| profile | No | ||
| rowCount | Yes | ||
| timezone | No | ||
| elapsedMs | Yes | ||
| truncated | Yes | True when a limit removed something: the result is a prefix, not the answer. | |
| nextCursor | No | ||
| limitReason | No | maxRows or maxBytes, when the result was truncated. |