--- title: "branch - Xata" description: "Commands for managing Xata database branches" source: "https://xata.io/docs/cli/branch" --- 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 ] [--project ] [--branch ] [--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 ] [--project ] [--branch ] [--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 ​ branch name string required The branch to describe **Aliases:** `view`, `show` ### ​create Create a new branch. ``` xata branch create [--organization ] [--project ] [--parent-branch ] [--name ] [--instance-type ] [--replicas ] [--region ] [--scale-to-zero ] [--inactivity-period ] [--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 ] [--project ] [--branch ] [--yes] [--json] [-h|--help] ``` ​ \--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 ] [--project ] [--branch ] [--database ] [--type ] [-h|--help] ``` ​ \--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 ] [--project ] [--branch ] [--database ] [--json] [-h|--help] ``` ​ \--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 ] [--project ] [--branch ] [--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 ] [--project ] [--branch ] [-h|--help] ``` ​ \--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 ] [--project ] [--branch ] [-h|--help] ``` ​ \--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](/docs/platform/branch#upgrading-postgresql-versions) for more details on upgrade requirements. ### ​wait-ready Wait for a branch to be ready. ``` xata branch wait-ready [--organization ] [--project ] [--branch ] [--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 ​ 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 ] [--project ] [--branch ] [--since ] [--start ] [--end ] [--metrics ] [--instances ] [--aggregations ] [--aggregation ] [--refresh ] [--output ] [-w|--watch] [--json] [-h|--help] [] ``` ​ \--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 ] [--project ] [--branch ] [--yes] [--json] [-h|--help] ``` ​ \--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 Was this page helpful? [Previous](/docs/cli/auth) [checkout](/docs/cli/checkout) [Next](/docs/cli/checkout)