Branching

Instant copy-on-write database branches for development, testing, and CI/CD

Overview

Database branches create full copies of your database in under 100ms using copy-on-write. Branches share base pages with the parent and only consume storage when data diverges.

Create a Branch

Via the API:

bash

curl -X POST https://api.scalix.world/api/v1/tenants/$TENANT_ID/timelines/$TIMELINE_ID/branch \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The request body accepts two optional fields:

Field	Description
`branch_lsn`	LSN to branch at. Omit (or pass `0`) to branch at the latest data.
`new_timeline_id`	Explicit id for the new branch timeline. Omit to have one generated.

Response (201 Created):

json

{
  "timeline_id": "b7e2c9d0-1f34-4a56-9c78-0d12e3f45a67",
  "parent_timeline_id": "00000000-0000-0000-0000-000000000001",
  "branch_lsn": 0,
  "endpoint": { "host": "10.0.0.12", "port": 5433 },
  "status": "ready"
}

The branch is restored from the parent timeline's durable base backup plus archived WAL, replayed to the branch LSN, and served by its own compute worker — the gateway routes connections scoped to the branch timeline to that worker. Your API key must belong to the tenant in the URL.

Passing a specific branch_lsn gives you a branch at a historical point — this is the same mechanism behind point-in-time recovery.

Delete a Branch

bash

curl -X DELETE https://api.scalix.world/api/v1/tenants/$TENANT_ID/timelines/$BRANCH_TIMELINE_ID \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Deleting releases the branch's compute worker and reclaims only the divergent pages. Branches that are neither queried nor deleted are reclaimed automatically after an idle period, so abandoned branches can't exhaust your compute pool.

How It Works

ScalixNova uses a page-level copy-on-write mechanism:

Creating a branch records a new timeline pointer — no data is copied
Reads on the branch resolve pages from the parent timeline
Writes create new pages only for the modified data
The branch diverges only where data changes

This makes branches effectively free until you write data.