# Branching with MongoDB > MongoDB never got Neon-style branching. Layerbase Cloud gives it to you: a serverless, Mongo-compatible database you branch from the dashboard in seconds, plus the same workflow locally with SpinDB or Layerbase Desktop. Published: 2026-06-10 Canonical: https://layerbase.com/blog/branching-with-mongodb > **DocumentDB update:** Standalone DocumentDB is a separate engine from FerretDB, although both use PostgreSQL-based document storage. See the [MongoDB-compatible engine chooser](/create/mongodb) for current availability. The FerretDB examples, compatibility findings, migration instructions and benchmark results in this article do not establish DocumentDB support. 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](https://cloud.layerbase.com/create?engine=ferretdb) 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](/migrate/mongodb-atlas) 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](/blog/mongodb-vs-ferretdb) 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](https://layerbase.com/docs/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?](https://layerbase.com/docs/cli)) ```bash npm i -g layerbase lbase create shop -e ferretdb --start # or -e mongodb ``` Load some data, then fork it: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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. ```bash 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](https://layerbase.com/desktop/download) 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 ```bash # 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, [compare qualified MongoDB-compatible engines](/create/mongodb). FerretDB supports this workflow, 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](/blog/mongodb-vs-ferretdb) 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](/migrate/mongodb-atlas) 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 [over 20 engines](https://layerbase.com/docs/cli) 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](/blog/branching-any-database) covers the general version.