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.
• Don't perform a resharding operation on the source cluster during a migration.
• 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 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" ]
       }
     )

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.