Execute SQL query
Execute a single SQL query or a batch of queries against a PostgreSQL branch.
Authentication: send the branch’s PostgreSQL connection string in the
Connection-String header. The control-plane API key (Bearer token) is
not accepted on the gateway host.
Routing: the target branch, region, and endpoint type are taken from the
hostname embedded in the connection string, which must match the request host.
See the Connection-String security scheme for the host format.
Single query: provide query (and optional params) at the top level.
Batch: provide queries as an array of query objects, or send the request body
as a JSON array. Batch queries execute within a single transaction.
Errors: PostgreSQL errors return 400 with their SQLSTATE in code and their
diagnostic fields. A 503 means the gateway could not reach the database: 08001
when a connection cannot be established and 08006 when an established connection
fails. A 503 does not guarantee that replaying a write is safe: a connection failure
can leave its outcome unknown.
Authorizations
Branch PostgreSQL connection string (postgres://user:pass@{branch}.{region}.xata.tech/db), including the embedded password. The hostname selects the target branch, region, and endpoint type (the -rw/-ro suffix, see EndpointType), and must match the request host. Obtain it from the Xata dashboard or the control-plane API. This is the only credential the gateway accepts; the control-plane API key (Bearer token) is rejected here. For the WebSocket endpoint (GET /v2) the same connection string is conveyed via the PostgreSQL startup message instead of this header.
Headers
Body
SQL query request. Provide either query for a single query or queries for a batch.
Response
Query executed successfully
- Option 1
- Option 2
Result of a single SQL query execution.