Raw SQL Query
db_raw_queryExecute raw SQL SELECT queries with mandatory LIMIT for complex joins, CTEs, and window functions that structured tools cannot express. Runs in a read-only transaction with row caps and blocked dangerous functions.
Instructions
Executes a raw SQL SELECT statement with a mandatory LIMIT clause. This is the escape hatch for queries that cannot be expressed with the structured tools (complex JOINs, CTEs, window functions, subqueries, etc.). All queries run inside a read-only, single-statement transaction with a configurable timeout (default 10 seconds).
When to use:
Complex JOINs across multiple tables
CTEs, window functions, or subqueries
Custom aggregations not supported by db_aggregate
Exploratory queries during development
Parameter guidance:
sql: the raw SQL statement (required). Must be a SELECT and MUST include a LIMIT clause. Example: "SELECT u.name, COUNT(o.id) FROM users u JOIN orders o ON o.user_id = u.id GROUP BY u.name ORDER BY COUNT(o.id) DESC LIMIT 10"
confirmed: set to true to acknowledge the raw query (currently informational)
Behavioral notes:
ONLY SELECT statements are allowed. INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, GRANT, and other DDL/DML are rejected.
The LIMIT clause is mandatory — queries without LIMIT are rejected.
Only single-statement queries are allowed (no semicolons separating multiple statements).
Dangerous functions (pg_read_file, COPY, pg_sleep, etc.) are blocked.
Results are capped at 5000 rows to prevent memory exhaustion.
Sensitive columns are automatically redacted in the output.
For write operations, use the structured tools (db_create, db_update_many, etc.).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Raw SQL statement. SELECT (must end with LIMIT) by default; non-SELECT requires confirmed: true, ALLOW_RAW_WRITES on the server, and a server that is not read-only | |
| database | No | Name of the database to query (from pgautopilot.json). Omit to use the current default database. | |
| confirmed | No | Explicit user confirmation to allow a single non-SELECT (write/DDL) statement |