Exec routes: run the request's SQL directly (CREATE ROUTE … AS $sql)

[asubbarao]

What

A route whose handler is exactly one parameter is an exec route:

CREATE OR REPLACE ROUTE sql POST '/sql' AS $sql;

quackapi recognises the single-$param handler, skips CREATE-time validation for it, and at request time executes the bound text as SQL on the request's connection. This lets a deployment serve /sql directly instead of looping back through quack_query('quack:localhost:…', $sql) (a second Quack connection per request).

Design

• Grammar: AS $<name> — the handler, trimmed (trailing ; stripped), is one $identifier and nothing else. $claims_* never qualifies (server-bound). Anything else is an ordinary handler and is still prepared/validated at CREATE.
• Binding: the request prepares a stand-in (SELECT $sql) so the parameter goes through the normal binding path: JSON body field, form field, query string, HEADER/COOKIE, and PARAM … MIN_LENGTH / DEFAULT all apply. The number-like-integer heuristic is skipped for the exec parameter (it is always VARCHAR SQL text).
• Execution: Connection::ExtractStatements (DuckDB's parser, incl. PRAGMA expansion) then Connection::Query(statement) for each statement in order — DDL, DML, PRAGMA, SET, INSTALL/LOAD, COPY. Each statement runs once.
• Result selection: the last statement's result (Query-farm/httpserver uses Connection::Query(string), which answers with the first row-producing statement). It flows through the existing response path: JSON default, Accept: text/csv / NDJSON / Arrow, route FORMAT, html/text columns, max_response_bytes. A final statement with no columns (SET, call-PRAGMA) answers [] rather than an empty body.
• Errors: the first failing statement stops the batch (later statements do not run) and answers 422 with the FastAPI-shaped detail: loc = the parameter's location (["body","sql"], ["query","q"]), type = value_error, msg = DuckDB's error, prefixed Statement i of n failed: for batches. Earlier statements are autocommitted, as in the DuckDB CLI.
• Limits/security: REQUIRE auth runs before any request SQL; query_timeout_ms bounds the whole batch (504). Row-access/masking policies cannot rewrite arbitrary SQL, so while any are bound the exec route fails closed (403, existing policy path). The pg_dsn native path and BODY TYPE rewrite are skipped for exec routes. OpenAPI documents the parameter and advertises no response columns.

Tests

test/sql/quackapi_exec_route.test (81 assertions, all pass locally against the freshly built test binary):
single SELECT; zero-row SELECT; multi-statement returns the last; DDL → DML → SELECT; TEMP table shared within a request and gone after; trailing SET → []; each statement once (INSERT side-effect counter + PRAGMA appears exactly once in DuckDB's QueryLog); error mid-batch → 422 with loc/type, Statement 2 of 3 failed, statement 1 committed and statement 3 not run; parser error runs nothing; conversion error 422; empty SQL / missing field 422; CSV body + NDJSON via Accept; html column mode; PARAM sql VARCHAR MIN_LENGTH 422/200; GET query-string exec route; REQUIRE 401 runs no SQL / 200 with key; row-access policy 403 then 200 after unbind; query_timeout_ms 504 on a batch; OpenAPI lists the route.

Real HTTP (test/conformance, 7 new cases): JSON, last-statement batch, CSV, Arrow (Accept: application/vnd.apache.arrow.stream, via community nanoarrow), 422 error shape, auth 401/200. Locally: 92 PASS / 0 FAIL.

Full test/sql/quackapi*: all pass (3308 assertions, 2 skipped). make format-ci-check clean.

Not in this PR

Switching dev's /sql route from quack_query to AS $sql happens after merge + release.

🤖 Generated with Claude Code