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

​
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