branch - Xata

The branch command helps you create, list, describe, and manage branches in Xata.

Subcommands

list

List all branches.

xata branch list [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help]

string

Organization ID

string

Project ID

string

Branch ID

boolean

Output in JSON format

boolean

Print help information and exit

Aliases: ls

describe

Describe a branch.

xata branch describe [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Output in JSON format

boolean

Print help information and exit

string

required

The branch to describe

Aliases: view, show

create

Create a new branch.

xata branch create [--organization <id>] [--project <id>] [--parent-branch <id>] [--name <name>] [--instance-type <type>] [--replicas <n>] [--region <region>] [--scale-to-zero <true|false>] [--inactivity-period <minutes>] [--json] [-h|--help]

string

Organization ID

string

Project ID

string

Parent branch ID. Pass “None” to create a branch without a parent.

string

Branch name

string

Type of instance for this branch

number

Number of replicas for the branch (0-4)

string

Region for the branch

boolean

Scale to zero status for the branch (true|false)

number

Inactivity period in minutes for the branch (15|30|60|120|180)

boolean

Output in JSON format

boolean

Print help information and exit

delete

Delete a branch.

xata branch delete [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Do not ask for confirmation, assume yes

boolean

Output in JSON format

boolean

Print help information and exit

string

required

The branch to delete

url

Print URL (connection string) for a branch. This command reads the connection details from the credentials endpoint, so your API key needs the credentials:read scope.

xata branch url [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [--type <type>] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

string

Database name

string

default:"primary"

Connection type. One of:

primary — direct access to the primary instance (default).
primary-or-replica — routed access to the primary or a read replica.
replica — read-only access guaranteed to use read replicas only. Requires at least one replica configured on the branch.
pooler — pooled access to the primary. Recommended for serverless and high-concurrency workloads.

boolean

Print help information and exit

string

required

The branch to get URL for

Aliases: connection-string Examples:

# Get the default (primary) connection string
xata branch url main

# Get a pooled connection string for serverless workloads
xata branch url main --type pooler

# Get a read-only connection string that targets replicas
xata branch url main --type replica

checkout

Checkout a branch.

xata branch checkout [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [--json] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

string

Database name

boolean

Output in JSON format

boolean

Print help information and exit

string

required

The branch to switch to

tree

List all branches as a tree.

xata branch tree [--organization <id>] [--project <id>] [--branch <id>] [--show-id] [-h|--help]

string

Organization ID

string

Project ID

string

Branch ID

boolean

Show branch IDs in the tree

boolean

Print help information and exit

Aliases: topology

get

Get a field from a branch description.

xata branch get [--organization <id>] [--project <id>] [--branch <id>] [-h|--help] <field>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Print help information and exit

string

required

The field to get (default: .catalog)

set

Set a field value for a branch.

xata branch set [--organization <id>] [--project <id>] [--branch <id>] [-h|--help] <field> <value>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Print help information and exit

string

required

The field to set. Supported fields include name, replicas, instance-type, hibernate, scale-to-zero, inactivity-period, and postgres-version.

string

The value to set. If omitted in interactive mode, the CLI will prompt you to select from available options.

Upgrading PostgreSQL version

Use the postgres-version field to upgrade to a newer minor version of PostgreSQL. Only compatible upgrades within the same major version and offering type are allowed.

# Interactive mode — select from available versions
xata branch set postgres-version

# Non-interactive — specify the target version directly
xata branch set postgres-version postgres:17.7

See Upgrading PostgreSQL Versions for more details on upgrade requirements.

wait-ready

Wait for a branch to be ready.

xata branch wait-ready [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Output in JSON format

boolean

Print help information and exit

string

required

The branch to wait for

metrics

Show branch metrics such as CPU, memory, and disk usage across instances.

xata branch metrics [--organization <id>] [--project <id>] [--branch <id>] [--since <duration>] [--start <iso>] [--end <iso>] [--metrics <list>] [--instances <list>] [--aggregations <list>] [--aggregation <avg|max|min>] [--refresh <duration>] [--output <table|json|ndjson|tui>] [-w|--watch] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

string

Time range ending now, such as 1h, 24h, or 7d

string

Start time as an ISO timestamp

string

End time as an ISO timestamp

string

default:"default"

Metrics to query: default, all, or a comma-separated list

string

default:"all"

Instances to query: all, primary, replicas, or comma-separated instance IDs

string

default:"avg,max,min"

Aggregations to query as a comma-separated list of avg, max, min

string

default:"avg"

Aggregation to render in table or TUI output. One of avg, max, min.

string

default:"10s"

Refresh interval for watch mode, such as 10s, 1m, or 500ms

string

default:"table"

Output format. One of table, json, ndjson, tui.

boolean

Refresh metrics continuously. -w is an alias for --watch.

boolean

Output in JSON format

boolean

Print help information and exit

string

The branch to show metrics for

Examples

# Show a one-shot snapshot of the default metrics
xata branch metrics my-branch

# Continuously refresh metrics in the interactive TUI
xata branch metrics my-branch --watch

# Same as above, using the short alias
xata branch metrics my-branch -w

# Stream NDJSON updates every 5 seconds for the primary instance
xata branch metrics my-branch -w --refresh 5s --instances primary --output ndjson

logs

Show PostgreSQL server logs for a Xata branch, across its primary and replica instances. Logs are useful for debugging slow queries, connection issues, replication problems, and other runtime behavior. See Logs for the dashboard viewer and the underlying API. This command requires the logs:read scope on your API key.

xata branch logs [--organization <id>] [--project <id>] [--branch <id>] [--level <level>...] [--instance <id>...] [--process <name>...] [--search <text>] [--start <iso|duration>] [--end <iso|duration>] [--limit <n>] [-f|--follow] [-o|--output <raw|json|ndjson|csv>] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

string

Filter by log level. One of debug, info, warning, error. Repeatable, up to 100 values.

string

Filter by instance ID. Repeatable, up to 100 values.

string

Filter by process name. Repeatable, up to 100 values.

string

Case-insensitive substring search in the log message body, up to 1024 characters. For regex filtering, pipe raw output to rg or grep.

string

default:"1h ago"

Start of the time range. Either an ISO timestamp (2026-07-30T09:00:00.000Z) or a duration relative to now (500ms, 30s, 15m, 1h, 7d, 2w).

string

default:"now"

End of the time range, in the same formats as --start.

integer

default:"100"

Maximum number of entries to return, between 1 and 1000. The CLI pages internally, so a limit above the API’s per-request maximum is fetched across several requests.

boolean

Poll for new entries continuously. -f is an alias for --follow. Cannot be combined with --output json, because a JSON array cannot be streamed.

string

default:"raw"

Output format. One of raw, json, ndjson, csv.

boolean

Output in JSON format. Equivalent to --output json.

boolean

Print help information and exit

string

The branch to show logs for

Output formats raw prints one entry per line as <timestamp> [<level> <instanceID> <process>] <message>. json prints a single array. ndjson prints one JSON object per line, which is the format to use when streaming into another process. csv emits the columns timestamp,level,instanceID,process,message; in follow mode the header row is written once, before the first batch. In follow mode the CLI polls every 2 seconds using a 5 second overlap window and de-duplicates entries, so an entry that arrives late is not printed twice. Log output can contain connection strings and other credentials. See Logs for what is redacted; the same rules apply to CLI output. Examples

# Errors from the last 15 minutes
xata branch logs my-branch --level error --start 15m

# Follow errors and pull out just the message text
xata branch logs my-branch -f --output ndjson | jq -r 'select(.level=="error") | .message'

# Regex search, which --search does not do, by piping raw output
xata branch logs my-branch --output raw | rg 'timeout|deadlock'

# Export one replica's Postgres process logs to a file
xata branch logs my-branch --process postgres --instance <replica-id> --output csv > logs.csv

query-insights

Inspect query statistics for a branch from the command line: which statements are slow, which are expensive, and what is running right now. Historical statistics come from PostgreSQL’s pg_stat_statements extension, and currently-running queries come from pg_stat_activity. See Query insights for the dashboard equivalent. Aliases: qi Running xata branch qi with no subcommand is equivalent to xata branch qi list. Before you start. Three prerequisites produce errors before any flag matters:

pg_stat_statements must be loaded. Run xata branch query-insights enable <branch>, which adds the extension to the preloaded libraries and requires a branch restart. Then wait for the branch with xata branch wait-ready <branch> --wake. The active subcommand is the exception: it reads pg_stat_activity and does not need the extension.
The branch must be healthy. Unlike logs and metrics, this command opens a direct PostgreSQL connection to the branch, so it cannot run against a branch that is hibernated or still provisioning. The error tells you to run xata branch wait-ready <branch> --wake.
Your API key needs the credentials:read scope. This is the scope that lets the CLI fetch the branch connection string, and without it every query-insights subcommand fails. logs and metrics are unaffected, because they go through the API rather than a database connection.

query-insights list

List historical query statistics for a branch, sorted by total execution time.

xata branch query-insights list [--organization <id>] [--project <id>] [--branch <id>] [--search <text>] [--type <list>] [--performance <list>] [--db <list>] [--role <list>] [--sort <field>] [--direction <asc|desc>] [--limit <n>] [--offset <n>] [-w|--wide] [-o|--output <table|json|ndjson|tui>] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

string

Match against the query text, database, or role

string

Filter by statement type as a comma-separated list of SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, OTHER

string

Filter by performance band as a comma-separated list of fast, moderate, slow

string

Restrict to one or more databases, comma-separated

string

Restrict to one or more roles, comma-separated

string

default:"total-time"

Sort field. One of total-time, mean-time, min-time, max-time, stddev-time, calls, rows, shared-hit, shared-read, shared-dirtied, shared-written, local-hit, local-read, local-dirtied, local-written, temp-read, temp-written, database, user.

string

default:"desc"

Sort direction. One of asc, desc.

integer

Maximum number of queries to return. Defaults to 50 for table and tui output, and 1000 for json and ndjson.

integer

default:"0"

Number of queries to skip, for paging

boolean

Show every pg_stat_statements metric in human-readable output. -w is an alias for --wide. Note that on metrics, -w is an alias for --watch instead.

string

default:"table"

Output format. One of table, json, ndjson, tui. tui requires an interactive terminal and errors otherwise.

boolean

Output in JSON format

boolean

Print help information and exit

string

The branch to show query statistics for

Aliases: ls In table output a leading ! marks any row with a high mean execution time or a low cache hit rate. Below the table the CLI prints how many queries are being shown, the list command that fetches the next page, and a Potential issues block naming each flagged query with the exact show command to run next. Machine-readable output. Both json and ndjson emit a single object of the shape { "total": <n>, "limit": <n>, "offset": <n>, "queries": [ ... ] }; ndjson is the same content on one line rather than one record per line. Individual statements are under queries, and the pg_stat_statements identifier is the queryid field:

xata branch qi list my-branch --output json | jq -r '.queries[].queryid'

query-insights show

Show the full statistics for one query.

xata branch query-insights show [--organization <id>] [--project <id>] [--branch <id>] [--db <name>] [--role <name>] [--json] [-h|--help] <queryid> [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

string

Database the query ran against, to disambiguate

string

Role that executed the query, to disambiguate

boolean

Output in JSON format

string

required

The pg_stat_statements query ID

string

The branch to query

Aliases: get A queryid is not unique on its own: the same normalized statement can be recorded separately for each database and role that ran it. When a query ID matches more than one row, the command prints a warning and exits with a non-zero status. Re-run it with --db and --role to select one. Non-JSON output also ends with a Potential issues block when the query’s mean execution time or cache hit rate crosses the same thresholds list uses.

query-insights active

Show queries that are running right now, and what they are waiting on. This subcommand reads pg_stat_activity and does not require pg_stat_statements. There is no equivalent view in the dashboard.

xata branch query-insights active [--organization <id>] [--project <id>] [--branch <id>] [--watch <seconds>] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

integer

Refresh every N seconds. This flag takes a number of seconds, not a boolean, and cannot be combined with --json.

boolean

Output in JSON format

string

The branch to inspect

Columns are PID, Age, State, Wait, DB, User, Client, and Query.

query-insights enable

Enable the pg_stat_statements extension on a branch.

xata branch query-insights enable [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

boolean

Output in JSON format

string

The branch to enable the extension on

This creates the extension and adds it to the branch’s preloaded libraries. A branch restart is required to load the library. Wait for the branch with xata branch wait-ready <branch> --wake before running list or show. You can also enable the extension from the Extensions settings of your branch. Enabling is not always permanent. If list or show return nothing on a branch where they worked before, check that the extension is still loaded and re-run enable. Operations that rebuild a branch’s contents, such as a migration into it, can drop the extension.

query-insights reset

Discard all accumulated query statistics for a branch by calling pg_stat_statements_reset().

xata branch query-insights reset [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] [<branch name>]

string

Organization ID

string

Project ID

string

Branch ID

boolean

Skip the confirmation prompt

boolean

Output in JSON format

string

The branch to reset statistics for

Resetting is branch-wide and cannot be undone. All historical query counters are discarded and begin rebuilding as new queries run.

The reset function requires elevated privileges; if permission is denied, ask an administrator to run it. Examples

# The slowest statements by average execution time
xata branch query-insights list my-branch --performance slow --sort mean-time

# Same thing, using the short alias and the default subcommand
xata branch qi my-branch --sort mean-time

# Full detail for one query
xata branch qi show -6744440887696913970 --db postgres --role postgres my-branch

# What is running right now, refreshed every 5 seconds
xata branch qi active my-branch --watch 5

# Feed the top 100 statements to another process
xata branch qi list my-branch --limit 100 --output ndjson | jq -r '.queries[].query'

rotate-password

Rotate the database password for a branch. This command reads the current username from the credentials endpoint, so your API key needs the credentials:read scope.

xata branch rotate-password [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] <branch name>

string

Organization ID

string

Project ID

string

Branch ID

boolean

Do not ask for confirmation, assume yes

boolean

Output in JSON format

boolean

Print help information and exit

string

required

The branch to rotate the password for

Global Flags

boolean

Print help information and exit

​Subcommands

​list

​describe

​create

​delete

​url

​checkout

​tree

​get

​set

​Upgrading PostgreSQL version

​wait-ready

​metrics

​logs

​query-insights

​query-insights list

​query-insights show

​query-insights active

​query-insights enable

​query-insights reset

​rotate-password

​Global Flags

Subcommands

list

describe

create

delete

url

checkout

tree

get

set

Upgrading PostgreSQL version

wait-ready

metrics

logs

query-insights

query-insights list

query-insights show

query-insights active

query-insights enable

query-insights reset

rotate-password

Global Flags