Migrate with mongomirror

Source MongoDB Deployment

• The source MongoDB deployment must be a replica set. If the source is a standalone MongoDB deployment, before running mongomirror, convert the standalone to a replica set.

• The source replica set must run MongoDB version 2.6 or higher.

• The source MongoDB replica set can't be an M0 Free cluster or M2/M5 shared cluster.

• The source MongoDB replica set can't contain data in time series collections.

• Don't change the featureCompatibilityVersion flag at any time during the procedure.

• When you migrate from MongoDB 4.4 or earlier to an Atlas cluster that runs MongoDB 5.0 or later, drop any geoHaystack indexes from your collections.

• mongomirror is not compatible with TTL indexes. Drop any existing TTL indexes and rebuild them when the migration process is complete. If you do not want to drop an existing index because it is important for query performance, contact support for alternative options.

• Don't make any namespace changes during the migration process, such as using the renameCollection command or executing an aggregation pipeline that includes the $out aggregation stage.

• You can't use the renameCollection command or the $out aggregation stage as part of initial sync, which runs as a part of the mongomirror process.

• You must not restart the primary during the initial sync stage of the migration.

• If your MongoDB deployment contains indexes with keys which exceed the Index Key Limit, before you start the live migration procedure, modify indexes so that they do not contain oversized keys.

Required Access on Source Replica Set

mongomirror must have network access to 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. The readAnyDatabase role on the admin database covers this requirement.

• Read the oplog. See Oplog Access.

• 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 run the appropriate commands in the mongosh:

• For source clusters a user must have the readAnyDatabase, clusterMonitor, and backup roles.

  To verify that the database user who will run the live migration process has these roles, run the db.getUser() command on the admin database.

  use admin
  db.getUser("admin")
  {
    "_id" : "admin.admin",
    "user" : "admin",
    "db" : "admin",
    "roles" : [
      {
        "role" : "backup",
        "db" : "admin"
      },
      {
        "role" : "clusterMonitor",
        "db" : "admin"
      }
      {
        "role" : "readAnyDatabase",
        "db" : "admin"
      }
    ]
  } ...

  In addition, the database user from your source cluster must have the role to read the oplog on your admin database. To learn more, see Oplog Access.

• For source clusters running MongoDB 3.4 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 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 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" ]
         }
       )

Destination Atlas Deployment

The destination Atlas deployment:

• Can't be an M0 Free cluster, M2, or M5 Shared cluster.

• Can't be a Serverless instance.

• Must be a replica set.

• Must have the version that is the same as or later than the source cluster MongoDB version. See Upgrade Path.

• Must not contain any namespaces that overlap with the source cluster. If mongomirror detects overlapping namespaces on the destination cluster it fails before starting the process. If your destination cluster contains overlapping namespaces, delete all data from the destination cluster with --drop, or list the namespaces to import from the source cluster with --includeNamespace.

• Must include in its IP access list either:

  • The public IP address of the server on which mongomirror is running, or

  • If set up for VPC peering, either the peer's VPC CIDR block (or a subset) or the Security Group of the peer VPC.

  Note

  To find the public IP address for any node in your cluster, use the nslookup tool from the command line. To learn more, see Do Atlas cluster's public IPs ever change?.

Required Access on the Destination Cluster

mongomirror must have network access to the destination cluster.

You must specify a database user with the Atlas admin role to run mongomirror. To learn more, see Add Database Users.