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 cannot be an M0 free cluster or M2/M5 shared cluster.
• 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 running MongoDB 5.0 or later, drop 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.
• If you must rename or drop a collection during the migration process, contact Atlas support.

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 running MongoDB 3.6 or later a user must have the readAnyDatabase, the clusterMonitor, and the backup roles.

  To verify that the database user that 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" ]
         }
       )

Target Atlas Deployment

The target 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 target cluster it fails before starting the process. If your target cluster contains overlapping namespaces, delete all data from the target 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.

Required Access on Target Cluster

mongomirror must have network access to the target cluster.

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