Migrate with mongomirror¶

Set up database user in the source replica set.¶

If the source replica set requires authentication, you must include user credentials when running mongomirror. You must specify a database user with, at a minimum, the following privileges:

• Read all databases and collections (i.e. readAnyDatabase on the admin database)
• Read the oplog.
• Run the getParameter command.

If no such user exists, create the user in your source MongoDB replica set. Different MongoDB server versions have different built-in roles. Select a built-in role based on your MongoDB server version and execute the appropriate commands in the mongo shell:

• For source clusters running MongoDB version 3.4 or later a user must have, at a minimum, both clusterMonitor and readAnyDatabase roles. For example:

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

  • For source clusters running MongoDB version 3.2 a user must have, at a minimum, both clusterManager and readAnyDatabase roles, as well as read access on the local database. This requires a custom role, which you can create with the following commands:

    use admin
    db.createRole(
         {
           role: "migrate",
           privileges: [
             { resource: { db: "local", collection: "" }, actions: [ "find" ] }
           ],
           roles: ["readAnyDatabase", "clusterManager"]
         }
       )
     db.createUser(
         {
           user: "mySourceUser",
           pwd: "mySourceP@$$word",
           roles: [ "migrate" ]
         }
       )

  • For source clusters running MongoDB version 2.6 or 3.0 a user must have, at a minimum, the readAnyDatabase role. For example:

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

Make note of the username and password for this user, as you must specify these credentials when running mongomirror.

Set up a database user in the target Atlas cluster.¶

You must specify a database user with the Atlas admin role to run mongomirror. See Add Database Users for documentation on creating a database user.

If no such user exists, create the user:

1. In the Security section of the left navigation, click Database Access. The Database Users tab displays.
2. Click Add New Database User.
3. Add an Atlas admin user.

Make note of the username and password selected for the new user, as you must specify these credentials when running mongomirror.

Update IP Access List.¶

If the host where you will run mongomirror is not in your cluster's IP Access List, 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.

Open the connect dialog.¶

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

Copy the target cluster host information.¶

You can get your Atlas cluster's hostname information from the Atlas application connection assistance UI.

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.

Start mongomirror.¶

Start mongomirror with the following options:

• --host set to the host string of the source cluster.
• --ssl 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:

mongomirror --host "MySourceRS/host1.example.net:27017,host2.example.net:27017,host3.example.net:27017" \
   --ssl \
   --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.

Stop your application.¶

This ensures that no additional writes occur on the source cluster.

Wait for mongomirror to report 0s of lag between the source and destination clusters.¶

This signifies that the source and destination clusters are in a consistent state.

Stop mongomirror.¶

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

Update client applications to use the Atlas cluster.¶

Update your client application(s) with the Atlas connection string provided via the Connect button on the cluster panel.

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