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, pick an environment label (Staging by default; None, Production, Development, Preview, and Backup are also available), and confirm. The label shows as a pill in your database lists and can be changed any time in the branch's Settings. One pair of labels carries behavior: a branch labeled Preview or Development is treated as ephemeral - it hibernates after 20 idle minutes and cannot be pinned always-on on shared infrastructure (it wakes on connect in ~1-5 seconds). A few conditions have to be met first:
- You must be the owner of the database. Branch and Reset from parent 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 16 engines: PostgreSQL, MySQL, MariaDB, Redis, Valkey, FerretDB, LibSQL, SQLite, DuckDB, TypeDB, ClickHouse, Meilisearch, Qdrant, QuestDB, InfluxDB, and Weaviate. FerretDB covers MongoDB workloads (it speaks the MongoDB wire protocol). CouchDB and TigerBeetle are excluded by design - they keep their cluster identity inside the data itself, so a copied data directory would be a second member of the same cluster rather than an independent database - and 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. A branch then shares data with its parent until the two diverge, so new branches appear in a second or two regardless of size and no full copy is made up front.
Turning Branching on affects 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. MySQL, MariaDB, and TypeDB are reached on their own dedicated port instead, so enabling Branching moves the database and assigns it a new port: take the updated connection string from Connect once the move finishes.
Reset a branch
Reset from parent 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. You will find it on the branch itself, both in the actions beside its name and in the Lineage section of its Overview tab, next to the parent it re-forks from and the time of the last fork.
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.
The confirmation names the parent and the time of the last fork, and it adds context about the branch you are about to replace: whether anything has used it since that fork, and whether other branches were forked from it. A branch that a Vercel or GitHub preview mapping uses as its staging database is called out by name, and if that mapping has Reset staging on every deploy turned off, the confirmation says so: nothing else ever resets that branch, so it may be holding data that was never meant to be replaced. Whenever any of that applies, you have to type the branch name before the reset button becomes available. A branch with none of it keeps the plain one-click confirmation.
A hibernated branch does not need waking first: Layerbase wakes the branch and its parent for the re-fork and lets both hibernate again afterwards. A branch you stopped, or one that has been archived, has to be started or restored before it can be reset. The button stays visible either way and tells you which it needs.
Backups on a branch
Branches are not backed up automatically. A branch starts as a copy of a database that already has its own backups, and preview branches are usually short-lived, so backing up both would store the same data twice. You can take a manual backup of a branch at any time.
If a branch holds work you want protected on its own, turn on automatic backups for it from its Backups tab and it follows the same schedule as any other database on your plan. See Backups for the full picture.
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.