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.

You can have it anyway. Think of it as Neon's branching combined with Atlas's document model, and the piece that joins them is FerretDB.

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, Mongo or Ferret

You do not even have to commit to FerretDB to get branching on your laptop. SpinDB branches both engines, because it branches at the filesystem, not inside the database. (What is SpinDB?)

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

Load some data, then fork it:

spindb 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:

spindb 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:

spindb 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 SpinDB into git once:

spindb 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
# SpinDB forks "shop" into a branch for feature/reviews automatically

The clever bit is the port. SpinDB 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
spindb 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, 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.

In the cloud

When it is time to host it, create a FerretDB database on Layerbase Cloud. It is the Mongo-compatible engine in the catalog, and because it is Postgres underneath, you can branch it from the dashboard the same way: hit Branch, get an isolated copy of the data in seconds, and connect a preview environment to it. That is the Neon workflow, on a Mongo-compatible database, fully managed.

Your laptop and your cloud both speak mongodb://. 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
spindb create shop -e ferretdb --start --connect

# Fork it
spindb branch shop shop-experiment

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

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

# Connection string for any branch
spindb url shop-experiment

SpinDB 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.