Gateway

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.

POST

/

sql

curl --request POST \
  --url https://{branch}.{region}.xata.tech/sql \
  --header 'Connection-String: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "SELECT id, name FROM users WHERE id = $1",
  "params": [
    42
  ]
}
'

{
  "fields": [
    {
      "name": "id",
      "tableID": 0,
      "columnID": 0,
      "dataTypeID": 23,
      "dataTypeSize": 4,
      "dataTypeModifier": -1,
      "format": "text"
    },
    {
      "name": "name",
      "tableID": 0,
      "columnID": 0,
      "dataTypeID": 25,
      "dataTypeSize": -1,
      "dataTypeModifier": -1,
      "format": "text"
    }
  ],
  "command": "SELECT",
  "rowCount": 1,
  "rows": [
    {
      "id": 42,
      "name": "Ada"
    }
  ],
  "rowAsArray": false
}

Authorizations

Connection-String

string

header

required

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

Array-Mode

enum<string>

When true, return rows as arrays instead of objects.

Available options:

true,

false

Raw-Text-Output

enum<string>

When true, return all values as strings without type conversion.

Available options:

true,

false

Batch-Isolation-Level

enum<string>

Transaction isolation level for batch queries.

Available options:

ReadCommitted,

ReadUncommitted,

RepeatableRead,

Serializable

Batch-Read-Only

enum<string>

When true, execute the batch transaction in read-only mode.

Available options:

true,

false

Batch-Deferrable

enum<string>

When true, execute the batch transaction in deferrable mode.

Available options:

true,

false

Body

application/json

SQL query request. Provide either query for a single query or queries for a batch.

query

string

SQL query to execute (single query mode).

params

any[]

Positional parameters for the query ($1, $2, ...).

queries

object[]

Array of queries for batch execution within a single transaction.

Show child attributes

arrayMode

boolean

Override array mode for this query (single query mode only).

Response

Query executed successfully

Option 1
Option 2

Result of a single SQL query execution.

fields

object[]

required

Column metadata for the result set.

Show child attributes

command

string

required

PostgreSQL command tag (e.g. SELECT, INSERT, UPDATE, DELETE).

rowCount

integer | null

required

Number of rows affected by the command.

rows

any[]

required

Result rows. Each row is an object (column-name keys) or an array (when array mode is enabled).

rowAsArray

boolean

required

Whether rows are returned as arrays (true) or objects (false).

WebSocket wire protocol proxyUpgrade to a WebSocket connection that proxies the PostgreSQL wire protocol. The client sends and receives PostgreSQL protocol messages over binary WebSocket frames. **Authentication:** the same branch connection string credential as the HTTP SQL endpoint is used, but it is supplied via the PostgreSQL startup message inside the wire protocol rather than an HTTP header. The control-plane API key (Bearer token) is not accepted.

⌘I

curl --request POST \
  --url https://{branch}.{region}.xata.tech/sql \
  --header 'Connection-String: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "SELECT id, name FROM users WHERE id = $1",
  "params": [
    42
  ]
}
'

{
  "fields": [
    {
      "name": "id",
      "tableID": 0,
      "columnID": 0,
      "dataTypeID": 23,
      "dataTypeSize": 4,
      "dataTypeModifier": -1,
      "format": "text"
    },
    {
      "name": "name",
      "tableID": 0,
      "columnID": 0,
      "dataTypeID": 25,
      "dataTypeSize": -1,
      "dataTypeModifier": -1,
      "format": "text"
    }
  ],
  "command": "SELECT",
  "rowCount": 1,
  "rows": [
    {
      "id": 42,
      "name": "Ada"
    }
  ],
  "rowAsArray": false
}