Branching

Isolated database branches for development, testing, and CI/CD

Overview

Database branches create a full, isolated, writable copy of your database in seconds. Each branch is restored from the parent timeline's durable base backup plus archived WAL and served by its own compute worker, so nothing a branch does can affect the parent.

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 permanently removes the branch's durable data — its base backups and archived WAL are purged from storage. The response reports the reclaimed object count:

json

{ "deleted": true, "purged_objects": 7 }

Deletion is idempotent and cannot be undone. The main timeline cannot be deleted through this endpoint (400) — it is the database itself.

Branches that are neither queried nor deleted are suspended automatically after an idle period, so abandoned branches can't exhaust your compute pool.

How It Works

Each branch is an independent timeline:

Creating a branch restores the parent's durable base backup and replays archived WAL up to the branch point
The branch gets its own compute worker and its own backup cycle
Writes on the branch never touch the parent — the two timelines are fully isolated from the moment the branch is created
Connections scoped to the branch timeline are routed to its worker by the gateway