Branching with MongoDB

Neon made one idea normal: branch your database the way you branch your code. Fork an isolated copy in seconds, point a preview deploy at it, delete it when the pull request merges. Postgres developers expect that now.

MongoDB developers never got it.

Atlas has snapshots, and you can restore one into a new cluster, but a restore is not a branch. It is slow, it costs you a whole cluster, and nobody runs it on every feature branch. The thing Neon made cheap and instant, forking the data, just is not part of the Mongo world.

Layerbase gives it to you, and the headline is the part that runs on the web: managed, serverless, Mongo-compatible branching in the cloud, no cluster to restore and nothing to maintain. You get the same workflow on your laptop too. The piece that makes both possible is FerretDB, a drop-in MongoDB replacement.

Neon-style branching on Layerbase Cloud

Create a FerretDB database on Layerbase Cloud and you have a serverless, Mongo-compatible database on the web. It uses the same mongodb:// connection string and the same MongoClient driver your app already speaks, so for application code it is a drop-in replacement for MongoDB. It scales to zero when idle and wakes on the next connection, so you are not paying for a cluster that sits there overnight.

Because FerretDB stores its documents in Postgres, you can branch it straight from the dashboard. Hit Branch, get an isolated copy of the data in seconds, and point a preview environment at it. Delete it when the pull request merges. No snapshot to schedule, no second cluster to spin up, no restore to wait on. That is the Neon workflow, on a Mongo-compatible database, fully managed.

This is the part most teams actually want: a hosted, serverless MongoDB drop-in that branches like Postgres, with nothing to run or babysit. The rest of this post is for when you want the same thing on your own machine.

FerretDB is MongoDB on Postgres

FerretDB speaks the MongoDB wire protocol on top of PostgreSQL. Same mongodb:// connection string, same MongoClient driver, same find, insertOne, and aggregation pipeline. Your documents are stored as JSONB in Postgres tables. It is Apache 2.0 licensed, with none of the SSPL questions your client's legal team flagged.

For the large majority of application code (find, insert, update, the common aggregation stages) it is a drop-in. You change a connection string and nothing else. The gaps are in the advanced features: change streams, $lookup joins, and built-in text search are not all there yet. If your app leans on those, read the MongoDB vs FerretDB comparison first. If it does not, you will not notice the difference, except that your database is now Postgres, which is exactly why you can branch it.

Branch it locally too, real Mongo or Ferret

Want to work on your laptop, or branch actual MongoDB rather than the compatible engine? You can do both. The Layerbase CLI (formerly SpinDB) branches both engines locally, because it branches at the filesystem, not inside the database, so a real MongoDB instance forks just as easily as FerretDB. (What is the Layerbase CLI?)

npm i -g layerbase
lbase create shop -e ferretdb --start   # or -e mongodb

Load some data, then fork it:

lbase branch shop shop-experiment

That is a copy-on-write clone. On macOS (APFS) and on Linux with ZFS, Btrfs, or XFS it is instant and shares disk blocks until the copy diverges. On plain ext4 it falls back to a full copy, which still works, it just takes a moment. Either way you now have a second database with the same data, running on its own port:

lbase url shop-experiment
# mongodb://127.0.0.1:27018/shop-experiment

Point a script at it, run the migration you are unsure about, drop a collection by accident. The original shop never moves. When you want a clean slate:

lbase branch reset shop-experiment   # re-fork from shop's current state

Branch on every git checkout

This is the part that feels like Neon. Wire the Layerbase CLI into git once:

lbase branch init --base shop

That writes a small .spindb/branch.json to the repo and installs a post-checkout hook. From then on, your git branch and your database branch move together:

git checkout -b feature/reviews
# The Layerbase CLI forks "shop" into a branch for feature/reviews automatically

The clever bit is the port. The Layerbase CLI keeps whichever branch matches your current git branch on the same stable port, so your mongodb://localhost:27017/shop connection string never changes. Check out main and you are back on the main data. Check out the feature branch and you are on its data. Your app config has no idea any of this happened.

git checkout main          # back to the main database
lbase branch prune        # clean up branches whose git branch is gone

Look at the data in Layerbase Desktop

Branching from the terminal is fine, but you usually want to see what you forked. Layerbase Desktop wraps SpinDB in an app for macOS, Windows, and Linux, and it has a document console built for MongoDB and FerretDB: a collection sidebar, a mongosh-style editor, and your documents as cards. Right-click any database and pick Branch to fork it from the GUI, then open the branch and run db.reviews.find() against the copy. Same engines, same binaries, just visible.

One mongodb:// from laptop to cloud

Your laptop and your cloud both speak mongodb://. Develop against a local MongoDB or FerretDB, branch it on every feature, then host the serverless FerretDB on Layerbase Cloud and branch it there too. The driver in your app does not change between them. The only new power you picked up is the one Mongo never gave you: a branch.

Useful commands

# Spin up a Mongo-compatible database locally
lbase create shop -e ferretdb --start --connect

# Fork it
lbase branch shop shop-experiment

# Throw away changes and re-fork
lbase branch reset shop-experiment

# Tie database branches to git branches
lbase branch init --base shop

# Connection string for any branch
lbase url shop-experiment

The Layerbase CLI runs more than 20 engines with this same branch workflow, so the trick that gives MongoDB its missing feature also works for Postgres, Redis, ClickHouse, and the rest. Branching with any database covers the general version.