From MongoDB Atlas

Atlas clusters move to Databasezy FerretDB today, and to the MongoDB (Percona Server) engine when it launches. The copy is mongodump piped into mongorestore.

MongoDB Atlas migration at a glance, from the migration source catalogue

Status	Available
Target engines	MongoDB (Percona Server) , FerretDB (MongoDB-compatible)
How we read it	Connection string
Continuous sync	No, copy only
Provider preset	atlas

Before you start

• A Databasezy FerretDB instance, or use --create.
• An Atlas database user with read access to the database you migrate.
• The egress addresses on the Atlas network access list.

Find the connection string

In Atlas, open the cluster, choose Connect, then Drivers, and copy the mongodb+srv:// string. Replace the user and password with your migration user’s.

MongoDB Atlas notes

• Add our egress IPs to the Atlas network access list.
• Atlas Search indexes and triggers are Atlas features and are not copied.

The SRV name resolves to the replica-set members, and every member must accept the egress addresses (the preset notes this as atlas.srv). Shared tiers (M0, M2, M5) throttle mongodump. FerretDB does not support every MongoDB feature, for example some index options, $text search and change streams; unsupported indexes are reported by the restore.

Migrate

Portal

1. Open the target FerretDB (MongoDB-compatible) instance (create one first if you need to) and choose the Migrate in tab.
2. Under Source, pick Connection string and paste the URL. The host is recognised as MongoDB Atlas; you can also pick it from the provider list.
3. Run Preflight and work through the checklist. Blocking items must be fixed before the copy starts.
4. Start the copy and follow Copy and Verify. Mismatches are listed per table or collection.
5. Point your application at the new instance. The Report step keeps the timings and verification results.

CLI

shell

# Dry run: print the preflight checklist and the plan, change nothing
zb migrate --from "mongodb+srv://migrate:[email protected]/app" --to inst_abc --dry-run

# Start it (or use --create --size s1 instead of --to to create the target)
zb migrate --from "mongodb+srv://migrate:[email protected]/app" --to inst_abc

zb migrate status mig_123

API

shell

curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/instances/inst_abc/migrations \
  -H "Authorization: Bearer $ZB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "kind": "connection_string",
    "url": "mongodb+srv://migrate:[email protected]/app",
    "provider": "atlas"
  },
  "mode": "copy"
}'

# Follow progress, preflight report and verification
curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/instances/inst_abc/migrations/mig_123 -H "Authorization: Bearer $ZB_API_KEY"

Verify

Verification compares document counts per collection and the number of indexes. Indexes or options the target does not support are listed in the restore report. Run your application’s tests against the new instance before you switch traffic.

Cutover

This source is copy only. Writes that reach the source after the copy starts are not carried over, so for a database that changes, stop writes before you start the copy (maintenance mode, or scale writers to zero), run the migration, check verification, then point the application at the Databasezy connection string.

Roll back

A migration never deletes anything on the source. Until you decommission it, rolling back means pointing the application back at the source. Writes made on Databasezy after you switched are not on the source; if you need them, copy them back before switching. Cancel a running migration with zb migrate cancel <mig_id>; partially restored data stays on the target, so restart with --drop-target or delete the instance.

Troubleshooting

Preflight connects to one member but the copy fails

Not every replica-set member allows the egress addresses. Add them at the project level of the network access list.

An index is missing on the target

FerretDB does not support that index type or option. The restore report names it; rewrite the query or wait for the MongoDB engine.

Preflight cannot connect to the source

Check that the source accepts connections from the egress addresses preflight prints, that the host is the public one and that the password has not been rotated. zb migrate --dry-run shows the exact URL that will be used after any rewrites.

Preflight lists blocking items

Each item has a machine code and a fix. Nothing is written to the target until every blocking item is resolved; warnings do not block.

For anything else, zb migrate status <mig_id> shows the failing step and its message. How migrations work describes every step.