API reference

SQL API reference

Run an authorized SQL query and interpret its result, limits, and failure responses.

The SQL API executes a submitted SQL string and returns columns, rows, execution time, and affected-row counts. It is restricted to superusers and is intended for administrative, analytical, or maintenance work—not as the normal application data interface.

🚫SQL can change or damage application data and may not be reversible. Use the Records API for application workflows, review write queries carefully, and avoid sending untrusted input as SQL.

POST /api/sql

The request must include a valid superuser authorization token. The query is required, may be at most 5,000 characters, and may contain multiple inline statements; the returned result describes the last statement.

POST/api/sql

Authorizationstringheaderrequired

Superuser authorization token.

querystringbodyrequired

SQL text, from 1 through 5,000 characters.

Response

200Query executed

400Invalid input or SQL execution failure

401Authorization is missing or invalid

403The authorized record is not a superuser

$_cURL

curl --request POST \
  --url http://127.0.0.1:8090/api/sql \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>"
}'

{ "execTime": 1, "affectedRows": 0, "columns": [{ "name": "count(*)", "type": "", "nullable": true }], "rows": [["1"]] }

bash

curl -X POST 'http://127.0.0.1:8090/api/sql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: SUPERUSER_TOKEN' \
  --data '{"query":"SELECT count(*) AS total FROM tasks"}'

The success object contains:

Field	Type	Meaning
`execTime`	integer	Query execution time reported by PocketBase.
`affectedRows`	integer	Rows changed by the statement, when applicable.
`columns`	array	Column metadata with `name`, `type`, and `nullable`.
`rows`	array	Result rows, represented as arrays matching `columns`.

The handler caps returned rows at 1,000. Empty queries fail validation. Malformed SQL and other database errors return status 400 with a message beginning Failed to execute query.

For authentication and superuser administration, see authentication model and manage superusers and the admin UI.