Skip to main content
A branch is an instant, isolated copy of your database. Branches share storage with their parent (copy-on-write), so they’re fast to create and cheap to maintain.

​
Why branches?

Traditional database workflows are painful:
  • Restoring a production backup takes hours
  • Dev environments drift from production
  • Testing migrations is risky
With branches:
  • Create a staging copy in seconds
  • Each developer gets their own isolated database
  • Test migrations safely before production
main (production)
├── staging (instant copy of main)
│   ├── feature-auth (copy of staging)
│   └── feature-billing (copy of staging)
└── dev-alice (copy of main)

​
List branches

const branches = await client.database.v1.branches.list('proj_abc123');

for (const branch of branches) {
  const marker = branch.isDefault ? '(default)' : '';
  console.log(`${branch.name} ${marker} - ${branch.status}`);
}
Response
[
  {
    "id": "branch_main_456",
    "name": "main",
    "isDefault": true,
    "parentBranchId": null,
    "status": "active",
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-01-15T12:00:00Z"
  },
  {
    "id": "branch_staging_789",
    "name": "staging",
    "isDefault": false,
    "parentBranchId": "branch_main_456",
    "status": "active",
    "createdAt": "2025-01-12T10:00:00Z",
    "updatedAt": "2025-01-14T15:00:00Z"
  }
]

​
Create a branch

// Create staging branch from main
const staging = await client.database.v1.branches.create('proj_abc123', {
  name: 'staging'
});

console.log(`Created branch: ${staging.id}`);
// Created branch: branch_staging_789

​
Parameters

ParameterTypeRequiredDescription
namestringYesBranch name (letters, numbers, hyphens, underscores)
parentBranchIdstringNoParent branch to clone from (defaults to main)

​
Response

FieldTypeDescription
idstringBranch ID
namestringBranch name
isDefaultbooleanWhether this is the default branch
parentBranchIdstringID of parent branch (null for main)
statusstringactive or suspended
createdAtstringISO 8601 timestamp

​
Use cases

​
Staging environment

Create a staging branch that mirrors production: 
// Create staging from main (production)
const staging = await client.database.v1.branches.create(projectId, {
  name: 'staging'
});

// Get connection string for staging
const conn = await client.database.v1.projects.getConnection(projectId, {
  branch: 'staging'
});

// Deploy staging app with this connection
console.log(`STAGING_DATABASE_URL=${conn.connectionUri}`);

​
Feature branches

Each feature gets its own database: 
// Create feature branch from staging
const featureBranch = await client.database.v1.branches.create(projectId, {
  name: 'feature-user-auth',
  parentBranchId: stagingBranchId
});

// Developer works on their isolated copy
// No risk of breaking staging or production

​
PR preview environments

Automatically create a database branch for each pull request: 
// In your CI/CD pipeline
const prBranch = await client.database.v1.branches.create(projectId, {
  name: `pr-${prNumber}`,
  parentBranchId: mainBranchId
});

// Set environment variable for preview deployment
process.env.DATABASE_URL = (await client.database.v1.projects.getConnection(
  projectId,
  { branch: `pr-${prNumber}` }
)).connectionUri;

​
Safe migration testing

Test database migrations without risking production: 
// 1. Create test branch from production
const testBranch = await client.database.v1.branches.create(projectId, {
  name: 'migration-test'
});

// 2. Get connection to test branch
const testConn = await client.database.v1.projects.getConnection(projectId, {
  branch: 'migration-test'
});

// 3. Run migrations against test branch
// If anything breaks, production is unaffected

// 4. Once verified, run against production

​
Branch workflow

A typical development workflow: 
1. main (production)
   │
   ├─→ Create 'staging' from main
   │   │
   │   ├─→ Create 'feature-x' from staging
   │   │   └─→ Develop, test, merge PR
   │   │
   │   └─→ Create 'feature-y' from staging
   │       └─→ Develop, test, merge PR
   │
   └─→ Deploy staging to production (main)
Branches use copy-on-write storage. A new branch only stores the differences from its parent, making them extremely fast to create and storage-efficient.

​
Branch statuses

StatusDescription
activeBranch is running and accepting connections
suspendedBranch is paused (compute suspended, data retained)