Skip to main content
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