> ## Documentation Index
> Fetch the complete documentation index at: https://xata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# branch

> Commands for managing Xata database branches

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

## Subcommands

### list

List all branches.

```bash theme={null}
xata branch list [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help]
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

**Aliases:** `ls`

### describe

Describe a branch.

```bash theme={null}
xata branch describe [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to describe
</ParamField>

**Aliases:** `view`, `show`

### create

Create a new branch.

```bash theme={null}
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]
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--parent-branch" type="string">
  Parent branch ID. Pass "None" to create a branch without a parent.
</ParamField>

<ParamField path="--name" type="string">
  Branch name
</ParamField>

<ParamField path="--instance-type" type="string">
  Type of instance for this branch
</ParamField>

<ParamField path="--replicas" type="number">
  Number of replicas for the branch (0-4)
</ParamField>

<ParamField path="--region" type="string">
  Region for the branch
</ParamField>

<ParamField path="--scale-to-zero" type="boolean">
  Scale to zero status for the branch (true|false)
</ParamField>

<ParamField path="--inactivity-period" type="number">
  Inactivity period in minutes for the branch (15|30|60|120|180)
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

### delete

Delete a branch.

```bash theme={null}
xata branch delete [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--yes" type="boolean">
  Do not ask for confirmation, assume yes
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to delete
</ParamField>

### url

Print URL (connection string) for a branch.

```bash theme={null}
xata branch url [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [--type <type>] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--database" type="string">
  Database name
</ParamField>

<ParamField path="--type" 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.
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to get URL for
</ParamField>

**Aliases:** `connection-string`

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
xata branch checkout [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [--json] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--database" type="string">
  Database name
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to switch to
</ParamField>

### tree

List all branches as a tree.

```bash theme={null}
xata branch tree [--organization <id>] [--project <id>] [--branch <id>] [--show-id] [-h|--help]
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--show-id" type="boolean">
  Show branch IDs in the tree
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

**Aliases:** `topology`

### get

Get a field from a branch description.

```bash theme={null}
xata branch get [--organization <id>] [--project <id>] [--branch <id>] [-h|--help] <field>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="field" type="string" required>
  The field to get (default: `.catalog`)
</ParamField>

### set

Set a field value for a branch.

```bash theme={null}
xata branch set [--organization <id>] [--project <id>] [--branch <id>] [-h|--help] <field> <value>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="field" type="string" required>
  The field to set. Supported fields include `name`, `replicas`, `instance-type`, `hibernate`, `scale-to-zero`, `inactivity-period`, and `postgres-version`.
</ParamField>

<ParamField path="value" type="string">
  The value to set. If omitted in interactive mode, the CLI will prompt you to select from available options.
</ParamField>

#### 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.

```bash theme={null}
# 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](/platform/branch#upgrading-postgresql-versions) for more details on upgrade requirements.

### wait-ready

Wait for a branch to be ready.

```bash theme={null}
xata branch wait-ready [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to wait for
</ParamField>

### metrics

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

```bash theme={null}
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>]
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--since" type="string">
  Time range ending now, such as `1h`, `24h`, or `7d`
</ParamField>

<ParamField path="--start" type="string">
  Start time as an ISO timestamp
</ParamField>

<ParamField path="--end" type="string">
  End time as an ISO timestamp
</ParamField>

<ParamField path="--metrics" type="string" default="default">
  Metrics to query: `default`, `all`, or a comma-separated list
</ParamField>

<ParamField path="--instances" type="string" default="all">
  Instances to query: `all`, `primary`, `replicas`, or comma-separated instance IDs
</ParamField>

<ParamField path="--aggregations" type="string" default="avg,max,min">
  Aggregations to query as a comma-separated list of `avg`, `max`, `min`
</ParamField>

<ParamField path="--aggregation" type="string" default="avg">
  Aggregation to render in table or TUI output. One of `avg`, `max`, `min`.
</ParamField>

<ParamField path="--refresh" type="string" default="10s">
  Refresh interval for watch mode, such as `10s`, `1m`, or `500ms`
</ParamField>

<ParamField path="--output" type="string" default="table">
  Output format. One of `table`, `json`, `ndjson`, `tui`.
</ParamField>

<ParamField path="-w, --watch" type="boolean">
  Refresh metrics continuously. `-w` is an alias for `--watch`.
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string">
  The branch to show metrics for
</ParamField>

**Examples**

```bash theme={null}
# 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.

```bash theme={null}
xata branch rotate-password [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] <branch name>
```

<ParamField path="--organization" type="string">
  Organization ID
</ParamField>

<ParamField path="--project" type="string">
  Project ID
</ParamField>

<ParamField path="--branch" type="string">
  Branch ID
</ParamField>

<ParamField path="--yes" type="boolean">
  Do not ask for confirmation, assume yes
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format
</ParamField>

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="branch name" type="string" required>
  The branch to rotate the password for
</ParamField>

## Global Flags

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>