Branching

Scribase branching gives every developer, feature branch, and pull request its own database that forks from production in under a second. Branches are cheap, isolated, and disposable.

Local branches

Local branches use copy-on-write Postgres snapshots inside .scribase/.

# Create a branch from the primary
scribase branch new my-feature

# Connect to it
psql "$(scribase branch url my-feature)"

# List all branches
scribase branch list

# Delete when done
scribase branch delete my-feature

Copy-on-write means: only the pages you write are copied. A branch that makes a small schema change uses almost no extra disk space.

Remote branches (control-plane)

Remote branches are registered environments linked to a parent for schema diffing and merging. They are the building block for pull-request preview environments.

PR preview workflow

# 1. Provision a preview environment
scribase env create acme store pr-42 preview schema-only us-east create-pr-42 72

# 2. Register it as a branch of production
scribase branch register acme store pr-42 --base production

# 3. Link it to the GitHub PR
scribase branch pr acme store pr-42 github acme/store 42

# 4. Apply the branch's migrations
scribase migrate acme store pr-42 --dir ./migrations --apply

# 5. Review the schema diff
scribase branch diff acme store production pr-42

# 6. Merge on approval
scribase branch merge acme store production pr-42

Branch data modes

When creating a preview environment, choose a data mode:

schema-only is the fastest and most common for PR previews. snapshot is better when tests need realistic data.

TTL (time-to-live)

Preview environments can be auto-deleted after N hours:

scribase env create acme store pr-42 preview schema-only us-east create-pr-42 72
#                                                                               ^^ 72-hour TTL

When the TTL expires, the operator's reconcile loop (the worker service) claims the preview and deletes it through the same audited delete operation as scribase env delete. Extend a preview before it expires with scribase env renew.

Merge conflict resolution

A three-way merge compares the base environment's schema at registration time (the merge base), the current base (production), and the head (the branch).

• No conflict: the changes apply cleanly.
• Conflict: both sides modified the same object. Use --force to have the head win, or resolve manually.

scribase branch merge acme store production pr-42 --force

Schema diff output

branch diff returns a list of changed objects:

{
  "changes": [
    { "kind": "table", "name": "payments", "action": "added" },
    { "kind": "column", "table": "orders", "name": "paid_at", "action": "added" },
    { "kind": "policy", "table": "payments", "name": "owner can read", "action": "added" }
  ]
}

Best practices

• Create one branch per feature or PR, not per developer.
• Use schema-only mode for CI test branches to avoid copying production data.
• Set a short TTL (24–72 hours) on preview environments to avoid accumulating stale branches.
• Always run branch diff before merging to review what changed.
• Run schema test against the branch before merging to catch policy regressions.