Navigation

Migrate with mongomirror

mongomirror is a utility for migrating data from an existing MongoDB replica set to a MongoDB Atlas replica set. mongomirror does not require you to shut down your existing replica set or applications.

Important

mongomirror does not import user/role data.

Prerequisites

Source

  • The source MongoDB deployment must be a replica set. If the source is a standalone MongoDB deployment, convert to a replica set first.
  • The source MongoDB replica set must be version 2.6 or greater.
  • The source MongoDB replica set cannot be an M0 (Free Tier) or M2/M5 shared cluster.
  • You should not change the featureCompatibilityVersion flag at any time during the procedure.

Target

  • The target Atlas cluster must be a replica set.
  • The target Atlas cluster should be empty or run mongomirror with the --drop option.
  • The target Atlas cluster cannot be an M0 (Free Tier), M2, or M5 shared cluster.
  • You should not change the featureCompatibilityVersion flag at any time during the procedure.

Procedure

1

Set up MongoDB user in the source replica set.

If the source replica set requires authentication, you must specify a source MongoDB user that has privileges to read any database, including the local database. For example, a user with backup role provides these privileges.

If the source replica set requires authentication and no such user exists, create the user in your source MongoDB replica set. For example, if the source replica set uses SCRAM-SHA1 authentication:

  1. Connect a mongo shell to the primary.

  2. Switch to the admin database and create a user with the backup role.

    copy 
    use admin
db.createUser( { user: "mySourceUser", pwd: "mySourceP@$$word", roles: [ "backup" ] } )
2

Set up MongoDB user in the target Atlas cluster.

To run mongomirror, you must specify a MongoDB user that has readWriteAnyDatabase and dbAdminAnyDatabase privileges in the Atlas cluster. For example, a user with Atlas admin role provides these privileges.

If no such user exists, create the user:

  1. Go to Clusters view, select the Security tab, and then Users.
  2. Click Add New User.
  3. Add an Atlas admin user.
3

Open the connect dialog.

From the Clusters view, click Connect for the Atlas cluster into which you want to migrate data.

4

Update IP Whitelist.

If the host where you will run mongomirror is not in the IP Whitelist, update the list. You can specify either:

  • The public IP address of the server on which mongomirror will run, or
  • If set up for VPC peering, either the peer’s VPC CIDR block (or a subnet) or the peer VPC’s Security Group.
5

Copy the target cluster host information.

  1. Click Connect Your Application.
  2. Click I am using driver 3.4 or earlier.
  3. Copy the connection string and paste into your preferred text editor.

The connection string should look similar to the following example. This example has been broken into multiple lines for readability:

mongodb://<username>:<PASSWORD>@
  00.foo.mongodb.net:27017,
  01.foo.mongodb.net:27017,
  02.foo.mongodb.net:27017/test?
  ssl=true&replicaSet=myAtlasRS&authSource=admin

Copy the value of replicaSet and append the host list as comma separated values, similar to the following:

myAtlasRS/00.foo.mongodb.net:27017,01.foo.mongodb.net:27017,02.foo.mongodb.net:27017

Use this value for the --destination option in the next step.

6

Start mongomirror.

Start mongomirror with the following options:

  • --host set to the host string of the source cluster.
  • --ssl set to true if the source cluster has TLS/SSL enabled.
  • --username to the source cluster username created for this procedure.
  • --password to the password for the source cluster username.
  • --authenticationDatabase to the database in the source cluster where the username specified to –username was created.
  • --destination to the Atlas cluster host string.
  • --destinationUsername to the target Atlas cluster username.
  • --destinationPassword to the password for the target Atlas cluster username.

Your final command should resemble the following example:

copy 
mongomirror --host "MySourceRS/host1.example.net:27017,host2.example.net:27017,host3.example.net:27017" \
   --ssl "true" \
   --username "mySourceUser" \
   --password "mySourceP@$$word" \
   --authenticationDatabase "admin" \
   --destination "myAtlasRS/00.foo.mongodb.net:27017,01.foo.mongodb.net:27017,02.foo.mongodb.net:27017" \
   --destinationUsername "myAtlasAdminUser" \
   --destinationPassword "atlasPassword"

See Options for more mongomirror options.

When you start mongomirror:

  1. First, mongomirror performs an initial sync, copying collections from the existing MongoDB replica set to the target cluster in Atlas. mongomirror does not copy the config database.
  2. After the initial sync, mongomirror continuously tails the replica set’s oplog for incoming changes and replays them on the target cluster in MongoDB Atlas.

Once started, mongomirror runs continuously until you shut down the process. To fully migrate to the Atlas, continue on to Switch to Atlas steps.

Switch to Atlas

After the mongomirror has performed the initial sync and has been tailing the replica set’s oplog, to switch over to Atlas cluster:

1

Stop write operations to the source replica set.

2

Wait for the Atlas cluster to be up to date with the last writes.

Continue to run mongomirror to finish tailing the oplog.

3

Stop mongomirror.

Once the Atlas cluster is up to date, stop mongomirror.

4

Update client applications to use Atlas cluster.

Update client applications to connect to the Atlas cluster.

For details on connections to Atlas, see Connect via Driver.

Additional Information

For more information on mongomirror, including behavior, options, and examples, see the mongomirror reference page.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.