Skip to main content
Branch list view showing all available branches in the project Xata’s branching system uses Copy-on-Write (CoW) at the storage layer to create instant database branches. Each branch contains the exact schema and data of the parent branch at the moment of creation, but after creation, branches are independent PostgreSQL instances. Learn more about how branching works.

​
Overview

The overview page provides a single pane of glass to understand the details of your branch. Branch overview showing branch details and configuration options
  • Connect: Copy a connection string or individual parameters
  • Health: View the health and state of your primary instance and replicas
  • Instance Details: Understand the instance health, hierarchy and metadata
  • Create Child: Create a child branch using the current branch as the source
  • Instance Health: Click into an instance node to quickly view the latest metrics
  • Rotate Credentials: Rotate the database password for the xata user for enhanced security
Branch node flyout showing quick actions and branch information

​
Branch Features

Queries

Execute and manage database queries across your branches.

Metrics

Monitor branch performance and usage across your instances within a branch.

Extensions

Extend your database functionality with extensions.

Schemas

Manage your database structure and schema.

Migrations

Apply schema changes to your database without downtime.

​
Settings

Configure branch-specific settings including instance details, compute and PostgreSQL parameters.

​
Instance Details

Configure the fundamental properties and settings for your branch instance. Branch settings showing instance details and configuration options
  • Branch Name: Set and modify the human-readable branch name
  • Replicas: Configure the amount of replicas for a branch
  • Instance Type: Configure the instance type for this branch
  • Storage: Adjust storage size for the branch in GB. Storage can only be increased, not decreased, with a maximum of 1024 Gi (1 TB). You are charged based on actual usage, not the configured limit. Note that 0.5-1% of the configured limit is reserved for filesystem overhead.
  • PostgreSQL Image: Select from available PostgreSQL images including standard postgres, and analytics-optimized. You can upgrade to newer minor versions (e.g., from 17.5 to 17.7) but cannot change the offering type or perform major version upgrades.

​
Compute

Configure scale-to-zero settings for cost optimization. Learn more about compute settings →

​
Rotate Password

Generate a new password for the PostgreSQL xata user on this branch. Existing connections keep working, but new connections must use the new password. You can rotate the password from the branch settings page or using the CLI: 
xata branch rotate-password <branch-name>
  • Existing database connections remain active during rotation
  • New connections will use the new password once rotation completes
  • PgBouncer automatically picks up the new password for connection pooling
  • There may be a brief period where credentials are unavailable during rotation

​
PostgreSQL Configuration

Fine-tune PostgreSQL parameters and settings for optimal database performance. Branch settings showing PostgreSQL configuration parameters
  • Connections: Configure connection and authentication settings
  • Resource Consumption: Configure memory and resource allotation settings
  • Planner: Configure query planner options
  • IO & Async Behaviour: Configure input/output and asynchronous behavior
  • Write-Ahead Log: Configure Write-Ahead logging (WAL)
  • Extensions: Configure extension-specific parameters (available parameters depend on your branch’s image type and PostgreSQL version)
Available PostgreSQL parameters and preload libraries depend on your branch’s image type (postgres or analytics) and PostgreSQL major version. Extension-specific parameters only appear when the extension is available for your image type.

​
Preloaded Libraries

Configure extensions and libraries to be preloaded with your branch. Extensions that require preloading must be added to this list before their configuration parameters become available in the PostgreSQL Configuration section. When you add an extension to the preload list, its parameters will become visible and configurable. If you remove an extension from the preload list, any configured parameters for that extension will be automatically removed from your branch configuration.

​
Upgrading PostgreSQL Versions

You can upgrade your branch to a newer minor version of PostgreSQL while maintaining the same major version and offering type. This allows you to benefit from bug fixes and performance improvements in newer PostgreSQL releases.

​
Upgrade Requirements

  • Minor versions only: You can upgrade from one minor version to another within the same major version (e.g., 17.5 → 17.7)
  • Same offering: The PostgreSQL offering type (postgres or analytics) must remain the same
  • No downgrades: You cannot downgrade to an older minor version
  • No major version changes: Major version upgrades (e.g., 16.x → 17.x) are not supported through this method

​
Example Upgrade

To upgrade a branch from PostgreSQL 17.5 to 17.7 using the API: 
curl -X PATCH "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "postgres:17.7"}'
Upgrading PostgreSQL versions will trigger a rolling update of your branch instances. Plan upgrades during maintenance windows to minimize impact on your applications.

​
Rotating database credentials

You can rotate the database password for the xata user to enhance security. This operation is asynchronous and typically completes within a few seconds.

​
Using the API

curl -X POST "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}/credentials/rotate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "xata"}'
After rotation completes, retrieve the new credentials: 
curl "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}/credentials?username=xata" \
  -H "Authorization: Bearer YOUR_API_KEY"
  • Existing database connections remain active during rotation
  • New connections will use the new password once rotation completes
  • PgBouncer automatically picks up the new password for connection pooling
  • There may be a brief period where credentials are unavailable during rotation

​
From the CLI

Use the Xata CLI to create and manage branches programmatically: 
# Create a new branch
xata branch create --name "staging" --parent-branch "main"

# List all branches
xata branch list

# Get branch details
xata branch describe staging
For more CLI commands, see the CLI Reference.