Database Migration

This How-to shows you how to migrate your MongoDB data from one cluster to another one. For example how to migrate from your existing on-premise MongoDB cluster to the IONOS MongoDB cluster.

This migration requires some downtime, as you need to stop write operations to your old cluster during dumping the data.

High level plan

The steps for a migration are as follows:

1. Preparations

2. Stop writes to old cluster - start of downtime

3. Dump data from old cluster using mongodump

4. Optionally: copy dump

5. Restore data into new cluster using mongorestore

6. Use the new cluster - end of downtime

Preparations

A place to run mongodump and mongorestore

You need one machine that can access the old cluster, that can run mongodump, and one machine that can access the new cluster, that can run mongorestore.

Both can happen on the same machine. If they're two different machines, you need a way to copy the data dump from one machine to the other.

Check MongoDB version

Both clusters need to be running the same major version. You can see the version in the greeting if you connect with mongosh or you can query it with db.version().

Access to old cluster

If your old cluster has access control enabled, you need a user with permissions for find to all databases. Easiest is to grant the backup role to the user that you want to use for dumping the data.

You can then verify that you can connect by using the command for mongodump mentioned in the section "Dump old data" and then aborting the dump with Ctrl-C.

User in new cluster

You need one user with write permissions to all databases that your dump contains.

Additionally you can't restore the users and roles via mongorestore. So you have to create all the users with their credentials and roles via the IONOS API. You can list all the users and roles in your old cluster with db.system.users.find() in the admin database and can then create them in the new cluster according to the documentation on User Management. You can't see the plain text password on your old cluster, so you need to collect them from wherever you stored them.

Dump data from old cluster

Caution: The use of --oplog isn't possible because it requires elevated privileges on restoring. Therefore you need to make sure that no write operations happen during the dump. Otherwise you get an inconsistent dump.

You can dump the data from the old cluster with this command:

mongodump --host="hostname:port" \
  --username="username" --password="password" \
  --authenticationDatabase "admin" \
  --gzip --archive=mongodb.dump

Optionally you can limit data using --db, --collection, or --query flags to only dump specific databases, collections, or documents.

Restore data in new cluster

You can restore the dumped date in the new cluster with this command:

mongorestore --uri "mongodb+srv://username:[e-mail]" \
  --gzip --archive=mongodb.dump \
  --nsExclude "admin.system.*"

admin.system.* resources are excluded, since you can't modify users and roles from inside MongoDB in an IONOS MongoDB cluster. You need to use the IONOS API for them.