Guide

Branching a database

A branch is a full, independent copy of a database with its own connection string. Use one to test a migration, run a risky query, or spin up a throwaway copy for a feature branch, all without touching the original. The parent is never modified by anything you do on a branch.

What a branch is

When you branch a database, Layerbase forks its data into a new database. The branch gets its own host, port, and credentials, so it has a separate connection string from the parent. From that point on the two are independent: writes to the branch never reach the parent, and writes to the parent never reach the branch.

Branches form a tree. You can branch a branch, and every database page shows its lineage so you can see which database a branch was forked from.

Create a branch

Open the database and choose Branch from its actions, give the branch a name, and confirm. A few conditions have to be met first:

• You must be the owner of the database. Branch and Reset change the owner's data, so team members who are not the owner do not see them.
• The source database must be running. Start it first if it is stopped or hibernated.
• The engine must be one that supports branching (see below).

Supported engines

Branching is available for these nine engines: PostgreSQL, MySQL, MariaDB, Redis, Valkey, FerretDB (MongoDB wire protocol), libSQL, SQLite, and DuckDB. Other engines are not branchable yet, so the Branch action does not appear for them.

Why some branches are instant and others take a moment

How fast a branch is created depends on where the database is stored. On standard storage, a branch is a full copy of the data. That can take a moment for a large database, and the source is briefly paused while Layerbase snapshots it.

You can make branches near-instant by turning on Branching for the database under its Settings tab. This moves the database onto copy-on-write storage, so a branch is created as a reflink that shares data with its parent until the two diverge. New branches then appear in a second or two regardless of size, and no full copy is made up front.

Enabling Branching moves the storage for that one database only. For engines routed by TLS SNI, such as Postgres and Redis on their shared ports, the connection string does not change when you enable it.

Reset a branch

Reset re-forks a branch from the parent's current data. It is destructive: every change you made on the branch is discarded and replaced with a fresh copy of the parent. Use it to throw away an experiment and start over from a clean slate.

The branch keeps its identity across a reset. Its host, port, and credentials stay the same, so any connection string you have already wired up keeps working. Only the data is replaced. This cannot be undone.

Deleting a branch tree

Deleting a branch on its own works like deleting any database. But if you delete a database that has branches forked from it, the delete cascades: the parent and its entire branch tree are removed together.

To prevent surprises, the confirm dialog lists every child branch that will be deleted alongside the parent. Deleting the tree is permanent and cannot be undone, so delete the child branches individually first if you want to keep the parent.

Plans and availability

Branching is available to every account, including Free. Branches count as databases and use storage like any other, so a large tree, or many full-copy branches, draws on your plan's storage and database limits.

Automatic branches for preview deployments

Everything above is manual branching from the dashboard. Layerbase also has a GitHub integration that can create and tear down branches automatically as part of your deploy workflow. See the GitHub integration guide for how that connects to your repository.