Skip to content
DB Branch

Concepts

Base

Section titled “Base”

A base is the original database that branches are cloned from. You create it with db-branch base create, choosing an engine version (--runtime mysql@8.4.13, for example) and optionally an SQL dump. Its branches run on a server of the same version.

A base can be started again to load more data (base start), then stopped and snapshotted (base snapshot). A base that a branch uses cannot be deleted.

Snapshot

Section titled “Snapshot”

A snapshot is the base at one point in time. Creating a base takes its first snapshot, and every later load, refresh or mask takes another. A new branch starts from the latest snapshot unless you pass --snapshot, so older points in time stay available.

Branch

Section titled “Branch”

A branch is a clone of a base snapshot, running as its own database server. Changes to it never reach the base. Useful options of branch create:

  • --ttl 72h deletes the branch automatically after that time. branch extend pushes the expiry later.
  • --init-sql or --init-file runs SQL once after cloning.
  • --access private|open chooses between a branch with its own password for the owner and admins, and one anyone can use with a shared password.

branch reset discards every change since the branch was created. branch delete removes it.

Copy-on-write

Section titled “Copy-on-write”

ZFS clones are copy-on-write (CoW). Creating a clone copies no data, and a branch takes new space only for the blocks it writes. Bases and branches use lz4 compression, so ten branches of one base take little more than the base until they start writing.

Each branch keeps its starting point as a CoW snapshot. A reset rolls back to it, so it finishes in seconds and runs no SQL again.

Refresh

Section titled “Refresh”

A refresh reloads a base from a source database on a schedule. DB Branch dumps the chosen databases, loads the dump into the base, deletes the dump and takes a snapshot. Existing snapshots and branches are not touched, and only new branches use the refreshed data.

Terminal window
echo "$SOURCE_PASSWORD" | db-branch base refresh set prod \
  --host db.internal --port 5432 --user dumper --databases app,billing --every 24h --password-stdin
db-branch base refresh show prod
db-branch base refresh run prod
db-branch base refresh off prod

The interval is at least 1 hour, and up to 20 databases can be copied. The source user needs read access only. The source password is stored in the cluster state in plain text, like branch passwords.

Masking

Section titled “Masking”

A raw production base should not be handed to developers. db-branch base mask writes a masked copy of one base into another, empty base and takes a snapshot of it:

Terminal window
db-branch base create dev --runtime postgres@18.6
db-branch base mask dev --from prod --masker greenmask --rules rules.yaml

Free masking tools are available as modules for Greenmask (PostgreSQL), Greenmask (MySQL, beta) and PostgreSQL Anonymizer. Greenmask itself is installed separately on each node. The snapshot records the source, the masking tool, a hash of the rules and who ran it.

You decide which columns to change and check the result. DB Branch and the masking tools only run the rules you give them. Masked data often still counts as personal data.

Approval of rules, checks and automatic re-masking after each refresh are planned for the Business plan.

© 2026 DB Branch