Branching with MongoDB

Short version: MongoDB has no branch primitive and Atlas snapshots are a restore, not a fork. The way to get Neon-style branching for a Mongo workload is FerretDB, which speaks the MongoDB wire protocol on top of Postgres, so the same mongodb:// string and the same MongoClient keep working while the database underneath is something Layerbase can clone copy-on-write. Branch it from the cloud dashboard in seconds, or branch either FerretDB or real MongoDB locally with the CLI.

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.

Getting your existing data in is a form, not a project. If it currently lives in Atlas or a self-hosted MongoDB, paste the connection string on the MongoDB Atlas migration page and Layerbase copies the collections, documents, and indexes into a managed FerretDB database, checks the document counts against your source when it finishes, and hands you a report naming anything it could not bring across. It reads the source once and never writes to it. It is a one-shot copy rather than live replication, so you still plan a cutover, but it gets you from an Atlas cluster to a branchable database without a mongodump.

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. Storage is the part worth getting right, because it changed. The old 1.x line shredded documents into JSONB columns. FerretDB 2.x, which is what Layerbase runs, sits on Microsoft's DocumentDB extension for Postgres (pg_documentdb_core), which gives Postgres a native BSON datatype and BSON-aware indexes instead of mapping documents onto JSON. Your data is stored as BSON, the same way Mongo stores it, inside a Postgres instance. FerretDB is Apache 2.0 and the DocumentDB extension is MIT, so both layers are permissive, 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.

That is the part no MongoDB host can match. Because a FerretDB database is a Postgres database wearing a Mongo interface, Layerbase branches it with the same copy-on-write filesystem mechanics we use for Postgres, MySQL, and ClickHouse: no export, no restore, no Mongo-specific machinery. A Mongo-compatible branch is just a branch, and it is instant.

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

FAQ

Can I branch MongoDB itself?

Locally, yes. The CLI branches at the filesystem, so a real MongoDB data directory forks exactly like any other. In the cloud the answer is FerretDB, because licensing keeps MongoDB uncreatable as a hosted engine on Layerbase, and a FerretDB database is a Postgres database wearing a Mongo interface, which is precisely why it branches.

Is FerretDB a drop-in for my application code?

For most of it. Same connection string, same driver, same find, insertOne, and ordinary aggregation pipelines. The gaps that catch people are change streams, $lookup, and built-in text search. Check your codebase against the MongoDB vs FerretDB comparison before anything else here matters.

How is branching different from restoring an Atlas snapshot?

A restore gives you a whole new cluster and takes as long as it takes. A branch is a copy-on-write clone that exists seconds later, shares blocks with its parent, and accepts writes right away. The difference shows up in how you use it: nobody restores a snapshot on every pull request, and forking per branch is the normal case here.

What happens to my connection string when I switch git branches?

Nothing. lbase branch init --base shop installs a post-checkout hook and the CLI keeps whichever branch matches your current git branch on a stable port. Your app keeps connecting to the same mongodb://localhost:27017/shop and gets that branch's data.

Can I move an existing Atlas database over?

Paste the connection string on the MongoDB Atlas migration page and Layerbase copies collections, documents, and indexes into a managed FerretDB database, then checks document counts against your source and reports anything it could not bring across. It reads the source once and never writes to it, so it is a one-shot copy rather than replication: you still plan the cutover yourself.

The Layerbase CLI runs 21 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.