Branches

Isolated database environments

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

cURL

curl https://api.case.dev/database/v1/projects/proj_abc123/branches \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

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

cURL

curl -X POST https://api.case.dev/database/v1/projects/proj_abc123/branches \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging"
  }'

Parameters

Parameter	Type	Required	Description
name	string	Yes	Branch name (letters, numbers, hyphens, underscores)
parentBranchId	string	No	Parent branch to clone from (defaults to main)

Response

Field	Type	Description
id	string	Branch ID
name	string	Branch name
isDefault	boolean	Whether this is the default branch
parentBranchId	string	ID of parent branch (null for main)
status	string	active or suspended
createdAt	string	ISO 8601 timestamp

Use cases

Staging environment

Create a staging branch that mirrors production:

cURL

curl -X POST "https://api.case.dev/database/v1/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging"
  }'

Feature branches

Each feature gets its own database:

cURL

# Create feature branch from staging
curl -X POST "https://api.case.dev/database/v1/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"feature-user-auth\",
    \"parentBranchId\": \"$STAGING_BRANCH_ID\"
  }"

PR preview environments

Automatically create a database branch for each pull request:

cURL

# Create a PR branch
curl -X POST "https://api.case.dev/database/v1/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"pr-$PR_NUMBER\",
    \"parentBranchId\": \"$MAIN_BRANCH_ID\"
  }"

# Get connection for preview deployment
curl "https://api.case.dev/database/v1/projects/$PROJECT_ID/connection?branch=pr-$PR_NUMBER" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Safe migration testing

Test database migrations without risking production:

cURL

# 1. Create test branch from production
curl -X POST "https://api.case.dev/database/v1/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "migration-test"
  }'

# 2. Get connection to test branch
curl "https://api.case.dev/database/v1/projects/$PROJECT_ID/connection?branch=migration-test" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

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

Status	Description
active	Branch is running and accepting connections
suspended	Branch is paused (compute suspended, data retained)