Getting started

What it is

DB Branch makes database branches from ZFS copy-on-write (CoW) snapshots, for MySQL and PostgreSQL. You build a base once, from an SQL dump or from a production database. After that, a branch is a clone of a base snapshot. Nothing is copied, so a branch is ready in seconds however large the base is. Each branch is its own database server, so every developer or pull request can have one.

On our 3-node test cluster, a PostgreSQL branch took 0.5 s and a MySQL branch 3 s, measured from the API call until the branch accepted connections.

Requirements


OS	Linux that installs packages with apt. Tested on Ubuntu 24.04 LTS.
Storage	A ZFS pool for bases and branches (tested with OpenZFS 2.2). Datasets use lz4 compression.
Databases	Tested with MySQL 8.0 and 8.4, and PostgreSQL 18.
Nodes	One machine works. Three or more make a cluster.
Memory	Each branch server gets a 128 MB cache by default.

There are no official minimum sizes yet. Our test cluster has one node with 6 vCPU and 11 GB, and two with 2 vCPU and 3 GB.

Install outline

Install the package on each node and point it at a ZFS pool:

sudo apt install db-branch
sudo db-branch init --pool tank

db-branch init prepares the node: the ZFS datasets, the ARC limit, the admin password and a TLS certificate. It prints the web console address and the admin password once. The password is also saved in /etc/db-branch/initial-admin-password.

First base and branch

Install an engine version, build a base from a dump, then branch from it:

db-branch runtime available postgres
db-branch runtime install postgres@18.6
db-branch base create prod --runtime postgres@18.6 --dump /srv/prod.sql.gz
db-branch branch create feature-x --base prod --ttl 72h
db-branch branch dsn feature-x

--ttl 72h deletes the branch automatically after 72 hours. branch dsn prints the connection URL, including the password. To connect through any node, see Connecting to a branch.

When you are done:

db-branch branch reset feature-x   # discard every change since creation
db-branch branch delete feature-x