scribase branch

Creates and manages database branches. Local branches use copy-on-write snapshots of the local Postgres cluster; remote branches are registered with the control-plane API and tied to pull requests or preview environments.

Local branch commands

These operate on the local .scribase/ workspace.

`branch new <name> [--schema FILE]`

Creates a new branch from the current primary database. Prints the branch connection string and returns immediately.

Terminal

scribase branch new my-feature
# postgresql://postgres:postgres@127.0.0.1:54399/postgres

With --schema, the schema is compiled and applied to the new branch:

Terminal

scribase branch new my-feature --schema ./schema.scribase

Copy-on-write branching is fast — typically under one second.

`branch list` (local)

Lists all local branches and their status.

Terminal

scribase branch list

Output:

my-feature               running   postgresql://...
old-experiment           stopped   postgresql://...

`branch url <name>`

Prints the connection string for a named branch.

Terminal

scribase branch url my-feature

`branch delete <name>`

Stops and removes a local branch cluster.

Terminal

scribase branch delete my-feature

Remote branch commands

These call the control-plane API and require SCRIBASE_API_URL and SCRIBASE_ACCESS_TOKEN.

`branch register <org> <project> <env> [--base <parent-env>]`

Registers an environment as a branch of another, capturing the parent's schema as the merge base. This is the first step before a branch merge or branch diff.

Terminal

scribase branch register acme store pr-42 --base production

`branch list <org> <project>`

Lists all remote branches registered for a project.

Terminal

scribase branch list acme store

`branch diff <org> <project> <base-env> <head-env>`

Shows the schema diff between two environments.

Terminal

scribase branch diff acme store production pr-42

Returns a list of changed objects: added, modified, and removed tables, columns, functions, and policies.

`branch merge <org> <project> <base-env> <head-env> [--force]`

Merges the schema from head-env into base-env.

Terminal

scribase branch merge acme store production pr-42

Without --force, the merge fails if there are conflicts. With --force, the head schema wins on any conflict.

`branch pr <org> <project> <env> <provider> <repo> <number> [--url-template <t>]`

Links a branch to a pull request. Supported providers: github, gitlab, bitbucket, generic.

Terminal

scribase branch pr acme store pr-42 github acme/store 42
scribase branch pr acme store pr-42 generic my-repo 42 --url-template "https://git.example.com/{repo}/pr/{number}"

Workflow example

Terminal

# 1. Create a branch for a feature
scribase branch new feat-payments

# 2. Develop against the branch
psql "$(scribase branch url feat-payments)"

# 3. Register the remote environment as a branch
scribase branch register acme store feat-payments --base production

# 4. Open a PR and link it
scribase branch pr acme store feat-payments github acme/store 12

# 5. Review the diff
scribase branch diff acme store production feat-payments

# 6. Merge when approved
scribase branch merge acme store production feat-payments