Skip to content
LayerbaseLayerbase

Migrate from MongoDB Atlas to DocumentDB, then branch it

6 min readMongoDBDocumentDBMigrationBranching

Short version: open the MongoDB Atlas migration page, allow the connection in Atlas Network Access, paste your mongodb+srv:// string with the database name on the end, and pause writes while the copy runs. You end up with a DocumentDB database that speaks the MongoDB wire protocol, so your driver and most of your code stay as they are. Atlas is only read, never modified, so it stays where it is until you decide to turn it off.

This is the written version of the Atlas chapter of the Layerbase walkthrough. The video shows it happening; this post covers the parts a demo skips.

Contents

Before you start

DocumentDB is an open source document database built on PostgreSQL that speaks the MongoDB wire protocol. It is not the MongoDB server, and that matters for a few features, so check these before you pick a date:

  • Views and time-series collections are not copied. They are named in the report so you can recreate what you need.
  • Some indexes are skipped. DocumentDB cannot create an index with a collation or a hidden index. Those are skipped whole, not created without their options, and named in the report.
  • Capped collections lose their cap. The documents come across; the size limit does not.
  • One collection can hold at most five million documents for the guided copy. Anything larger is refused up front, and support can help with a bigger move.

If you lean on Atlas Search, change streams or heavy $lookup aggregation, test those queries against the new database before you commit. MongoDB Atlas alternatives has the full list of cases where staying on Atlas is the better call.

You do not need a paid plan to try this. DocumentDB is on the Free plan, so a small database can go through the whole process before you spend anything.

Step 1: Allow the connection in Atlas

This is the step that fails most often. Atlas refuses connections from any address that is not on its IP access list, and the copy runs from Layerbase's servers, not your laptop.

In Atlas, open Security, then Network Access, and add an entry that lets the copy in for as long as it runs. Remove it once the migration is done. A cluster reachable only through private endpoints or VPC peering cannot be read from outside, so that setup needs a public route for the duration.

While you are in Atlas, make sure the database user you will paste has read access to the database you are moving.

Step 2: Paste the connection string

In Atlas, go to Database, then Connect, then Drivers, and copy the string. Add the database name to the path if it is not there:

text
mongodb+srv://appuser:PASSWORD@cluster0.abc123.mongodb.net/shop

Two things the form will reject: a string without a database name, and a mongodb:// string that lists several hosts. Use the +srv form or a single host. Self-hosted MongoDB works too, as long as it is reachable from the public internet.

DocumentDB is the default target. FerretDB, the other MongoDB-compatible engine, is there as an option if you prefer it; FerretDB vs DocumentDB has the measured difference.

Step 3: Run the copy

The copy reads your live database. It is not a point-in-time snapshot, so documents written partway through can land unevenly across collections. Pick a quiet window or pause writes while it runs.

Every collection comes across with its documents and ordinary indexes. When it finishes, document counts are compared against the source.

Step 4: Read the report

The migration report is where anything that did not come across is written down: skipped indexes with their definitions, views, time-series collections, and any count that did not match. An empty list of problems is what you want. A non-empty one tells you exactly what to recreate by hand, and it is far better than finding out from a slow query in production.

Step 5: Check it yourself

The report checks counts. You should still look at the data with the tools you use every day. Copy the connection string from the database page and open mongosh against both sides:

javascript
// Run on Atlas and on the new database, then compare
db.getCollectionNames().sort()

db.getCollectionNames().forEach((name) => {
  print(name, db.getCollection(name).countDocuments())
})

db.orders.getIndexes()

Then run the three or four queries your app depends on most, with .explain() if any of them is hot. The answers should match, and the plans should use the indexes you expect.

Step 6: Branch it

This is the part Atlas does not have at any tier. Once the data is in, create a branch from the database page: a full copy of the database you can write to, drop collections in, or run a migration script against, without touching the original. Delete it when you are done, or reset it to match the parent again.

I use a branch for every change I am unsure about. Write the migration script, run it on a branch, look at the result, and only then run it on the real database. Branching with MongoDB goes further, and if you deploy on Vercel, each preview deployment can get its own branch automatically: A database branch for every Vercel preview.

Cutting over

The cutover is one environment variable. Point MONGODB_URI (or whatever your app calls it) at the new connection string and deploy. Your Node driver, Mongoose or PyMongo setup does not change.

A safe order:

  1. Do a trial run first: copy into a new database, point staging at a branch of it, and fix whatever the report and your tests turn up.
  2. For the real move, pause writes on Atlas, run a fresh copy into a new database, and check its report.
  3. Ship the environment variable change, then resume writes.
  4. Keep Atlas around, read-only, until you are sure. Then remove the Network Access entry and shut it down.

FAQ

Is this live replication?

No. It is a one-time copy. If the source kept changing after a trial run, do the real copy at cutover time with writes paused, as in the order above.

Will my MongoDB driver work?

Yes. DocumentDB speaks the MongoDB wire protocol, so the official drivers connect to it with a normal connection string.

Can I go to PostgreSQL instead?

Yes, as a second step. Once the data is on Layerbase, the MongoDB to PostgreSQL conversion turns collections into tables with a mapping you review first: Convert MongoDB to PostgreSQL with a mapping you can review.

What happens to my Atlas cluster?

Nothing. The migration only reads from it. You turn it off when you are ready.

Start on the MongoDB Atlas migration page, or create an empty DocumentDB database and look around first.

Keep reading