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]

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--json

boolean

Output in JSON format

-h, --help

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

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]

--organization

string

Organization ID

--project

string

Project ID

--parent-branch

string

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

--name

string

Branch name

--instance-type

string

Type of instance for this branch

--replicas

number

Number of replicas for the branch (0-4)

--region

string

Region for the branch

--scale-to-zero

boolean

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

--inactivity-period

number

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

--json

boolean

Output in JSON format

-h, --help

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--yes

boolean

Do not ask for confirmation, assume yes

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

string

required

The branch to delete

url

Print URL (connection string) for a branch.

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

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--database

string

Database name

--type

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.

-h, --help

boolean

Print help information and exit

branch name

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--database

string

Database name

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

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]

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--show-id

boolean

Show branch IDs in the tree

-h, --help

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

-h, --help

boolean

Print help information and exit

field

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

-h, --help

boolean

Print help information and exit

field

string

required

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

value

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>

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

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>]

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--since

string

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

--start

string

Start time as an ISO timestamp

--end

string

End time as an ISO timestamp

--metrics

string

default:"default"

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

--instances

string

default:"all"

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

--aggregations

string

default:"avg,max,min"

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

--aggregation

string

default:"avg"

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

--refresh

string

default:"10s"

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

--output

string

default:"table"

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

-w, --watch

boolean

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

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

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

rotate-password

Rotate the database password for a branch.

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

--organization

string

Organization ID

--project

string

Project ID

--branch

string

Branch ID

--yes

boolean

Do not ask for confirmation, assume yes

--json

boolean

Output in JSON format

-h, --help

boolean

Print help information and exit

branch name

string

required

The branch to rotate the password for

Global Flags

-h, --help

boolean

Print help information and exit

​Subcommands

​list

​describe

​create

​delete

​url

​checkout

​tree

​get

​set

​Upgrading PostgreSQL version

​wait-ready

​metrics

​rotate-password

​Global Flags

Subcommands

list

describe

create

delete

url

checkout

tree

get

set

Upgrading PostgreSQL version

wait-ready

metrics

rotate-password

Global Flags