mongomirror

Mongomirror is End of Life (EOL) as of July 31st 2025, with mongosync taking its place. MongoDB will no longer provide any updates, security patches, or support of any kind. Mongosync provides significant enhancements in features, performance, and reliability compared to mongomirror. Please note that direct migration into Atlas with mongosync will only be supported for source cluster versions 5.0 and above. For other migration options, please refer to our self-managed tools. If you choose to use mongomirror past its EOL date, please note that mongomirror is only compatible with MongoDB 6.0 and below. Attempts to use mongomirror against newer versions may fail to connect or encounter other errors, which may or may not be silent.

mongomirror When you use mongomirror with a namespace filter, transactions on the source with namespaces that are outside of the scope of the includeNamespace <database.collection> are considered undefined behavior and incur potential data loss.

mongomirror is a tool for manually migrating data from an existing MongoDB replica set to a MongoDB Atlas replica set. See also Download mongomirror.

Syntax

To run mongomirror, you must specify:

• The source replica set and the target Atlas replica set.

• A user in the Atlas cluster with appropriate privileges, the corresponding password, and appropriate privileges, if the source replica set requires authentication.

mongomirror --host <sourceReplSet> \
   --destination <atlasCluster> \
   --destinationUsername <atlasAdminUser> \
   --destinationPassword <atlasPassword> \
   [Additional options]

You can specify some options in the config file instead of including them in the command.

Options

mongomirror

--host <host> The host information for the source replica set. Specify the replica set name and a seed list of the members, as in the following:

<RSname>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>

--username <username> If the source replica set requires authentication, the name of a user in the source replica set with privileges to read any database, including the local database. A user with the backup role provides the appropriate privileges. For details on the specific privileges required, see Required Access on Source Replica Set.

--password <password> Password for the user specified in --username.

--authenticationDatabase <authenticationDatabase> The database in the source replica set where the user specified in --username was created. The authentication database for:

• SCRAM-authenticated users is the admin database.

• X.509-authenticated users is the $external database.

• AWS IAM-authenticated users is the $external database.

To learn more, see Authentication Database.

--authenticationMechanism <authenticationMechanism> The authentication mechanism to use to authenticate the user to the source replica set.

To learn more, see Authentication Mechanisms.

--awsSessionToken New in version 0.10.0

An AWS session token for use with the MONGODB-IAM authentication mechanism.

--compressors <snappy,...> New in version 0.9.0

Comma-separated list of compressors to enable. Use 'none' to disable. Default: snappy,zstd,zlib

--config=<file> YAML (Yet Another Markup Language) file that stores options and values for mongomirror. Specify the file using relative or absolute paths to run mongomirror with the options that the file contains.

The config file supports the following options:

• password password

• sslPEMKeyPassword password

• destinationPassword password

• uri source cluster URI connection string

Specify options in the config file using the option: value syntax. Don't include -- before options in the config file. If you set an option in the configuration file, you don't need to specify that option within the mongomirror command.

Create a config file called myconfig.yaml that contains the following:

password: <passwordForUser>
destinationPassword: <passwordForDestinationUser>

You can run mongomirror without including the --password and --destinationPassword flags:

mongomirror --host <sourceReplSet> \
   --ssl \
   --username <atlasAdminUser> \
   --destinationUsername <atlasAdminUser> \
   --config=myconfig.yaml \
   --destination <atlasCluster> \
   [Additional options]

--destination <destination> The host information for the target Atlas replica set.

Specify the replica set name and a seed list of the members, as in the following:

<RSname>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>

--destinationAuthenticationDatabase <authentication database> Authentication database for the database user in the Atlas cluster. The authentication database for SCRAM-authenticated users is the admin database.

To learn more, see Database User Authentication.

--destinationAuthenticationMechanism <authentication mechanism> Authentication mechanism for the database user in the Atlas cluster. Atlas offers the following forms of authentication for database users:

To learn more, see Database User Authentication.

--destinationUsername <Atlas user name> Name of a database user in the Atlas cluster with privileges to read, write, and admin any database. A user with the Atlas admin role provides the appropriate privileges. For details on the specific privileges required, see Required Access on the Destination Cluster.

--destinationPassword <password> Password of the database user specified in --destinationUsername.

--drop Flag that indicates that mongomirror should drop all user collections (viewable in each database with listCollections) on the target cluster. This option doesn't drop internal collections like local.system* and the oplog.

--noIndexRestore New in version 0.10.0

Omit indexes when migrating data.

--includeNamespace <database.collection> Specify a namespace on the source cluster to mirror to the target cluster. May be provided multiple times.

If a transaction spans multiple namespaces, only write operations applied to the namespaces specified in --includeNamespace or --includeDB are applied to the destination cluster.

--includeDB <database> Specify a database on the source cluster to mirror to the target cluster. May be provided multiple times.

If a transaction spans multiple namespaces, only write operations applied to the namespaces specified in --includeNamespace or --includeDB are applied to the destination cluster.

--ssl Enables TLS/SSL encrypted connections to the source replica set.

--sslPEMKeyFile <file> The .pem file if the source replica set requires clients to present a certificate. The .pem file contains both the TLS/SSL certificate and key. Specify the file using relative or absolute paths.

--sslPEMKeyPassword <value> Password to decrypt the certificate-key file specified in --sslPEMKeyFile. Use if the --sslPEMKeyFile is encrypted.

--sslCAFile <file> The .pem file that contains the root certificate chain from the Certificate Authority(CA) for the source replica set. Specify the file using relative or absolute paths.

--sslCRLFile <filename> The .pem file that contains the Certificate Revocation List for the source replica set. Specify the file using relative or absolute paths.

--sslAllowInvalidHostnames Deprecated. Use tlsInsecure instead.

Disables the validation of the TLS/SSL certificates presented by the source replica set. Allows mongomirror to connect to the source replica set if the hostname in the certificates does not match the specified hostname.

This option skips all certificate validation, which may result in accepting invalid certificates.

--sslAllowInvalidCertificates Deprecated. Use tlsInsecure instead.

Bypasses the validation checks for certificates presented by the source replica set. When using the --allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

This option skips all certificate validation, which may result in accepting invalid certificates.

--tlsInsecure Bypasses the validation checks for the server's certificate chain and host name. This allows you to use invalid certificates and host names.

This replaces the deprecated sslAllowInvalidHostnames and sslAllowInvalidCertificates options.

--gssapiServiceName <name> If the source replica set uses Kerberos authentication, the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--gssapiHostName <host> If the source replica set uses Kerberos authentication, the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.

This option is available only in MongoDB Enterprise.

--readPreference <read preference> Deprecated since version 0.9.0

mongomirror always reads from the primary unless the source is a single host without a replica set name, in which case it makes a direct connection only to that host.

--writeConcern <write concern> mongomirror always uses majority write concern.

--numParallelCollections <num>, -j <num>

Default: 4

The number of collections to copy and restore in parallel.

--bypassDocumentValidation mongomirror always bypasses document validation.

--bookmarkFile <file> Default: mongomirror.bookmark

Name of the oplog timestamp bookmark file.

--forceDump Flag that indicates that mongomirror resync all source collections, even if a nonempty bookmark file exists.

--oplogPath <path> New in version 0.5.0

Enables mongomirror to buffer the initial sync oplog window to disk. When you specify a value for this option, mongomirror streams the source oplog entries to the specified directory in a single file: <oplogPath>/oplog-mongomirror.bson.sz. After the entire oplog file is replayed to the destination cluster, mongomirror removes the file and starts tailing the source oplog without buffering.

By default, mongomirror streams oplog entries from the source and applies them to the destination cluster. However, the migration may fail if the source oplog is not large enough to contain the entire initial sync oplog window. To avoid this error, you can either increase the size of the source oplog, or specify this option to ensure that the source oplog will not run out of space during the migration process.

There must be enough disk space to accommodate all of the source oplog entries that occur during the initial mongomirror sync.

For example, if the source oplog is 10 GB and covers 24 hours of changes, and mongomirror's sync is estimated to take 48 hours, there must be at least 20 GB of free disk space in the specified directory.

--oplogBatchSize <num> Default: 10,000

Specify the number of oplog entries to send as a batch. mongomirror allows up to a maximum data volume size of 16 MB of documents to send as a batch.

--httpStatusPort <num> Directs mongomirror to start an HTTP server on the specified port. You can retrieve the current status of mongomirror by issuing an HTTP GET request to http://localhost:<num>.

When running with --httpStatusPort, mongomirror does not exit when it encounters an error. Instead, it logs the error as normal and reports the error over HTTP to the specified port.

mongomirror returns a document in response to the HTTP request. The following example syntax represents all the possible output fields - the actual response may only return a subset of these fields. See the subsequent table for a description of the fields and when to expect them.

{
   "stage" : "<stage Name>",
   "phase" : "<phase Name>",
   "details" : {
      "currentTimestamp" : "<BSON timestamp>",
      "latestTimestamp" : "<BSON timestamp>",
      "lastWriteOnSourceTimestamp" : "<BSON timestamp>",
      "<namespace>" : {
         "complete" : <boolean>,
         "copiedBytes" : <integer>,
         "totalBytes" : <integer>,
         "createIndexes" : <integer>
      },
      ...
   },
   "errorMessage" : "<error message>"
}

The following table describes each field and its possible values:

--collStatsThreshold <num> New in version 0.9.0

Maximum number of collections which may exist before collStats is disabled. Use -1 to always run collStats or 0 to never run collStats. Default: -1

--removeAutoIndexId New in version 0.12.0

Removes the autoIndexId option from collections during the initial sync to the target cluster. Also removes the autoIndexId option from any collections that mongomirror creates during the migration.

--preserveUUIDs Allows Atlas to preserve UUID during live migration. This option works only with the live migration process that Atlas runs. If you use the --preserveUUIDs option on the command line, it will fail due to permission errors. These errors are expected because this option isn't intended to be used on the command line in a self-managed migration process that runs mongomirror.

Examples

Migrate a Replica Set to Atlas: No Authentication on Source

The following example migrates from a source replica set that doesn't require authentication:

mongomirror --host  sourceRS/source-host1:27017,source-host2:27017 \
         --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
         --destinationUsername myAtlasUser \
         --destinationPassword myAtlasPwd

To migrate from a source replica set that doesn't require authentication, run mongomirror with the following options:

• --host sourceReplSet/seed list of members

• --destination Atlas Cluster

• --destinationUsername atlasUser

• --destinationPassword atlasPassword

For the target, specify the replica set name followed by a seed list of members in the following format:

<replicaSetName>/<host1>:<port1>,<host2>:<port2>,<host3>:<port3>,...

The specified user must have the Atlas admin role on Atlas.

Migrate a Replica Set: Source Replica Set Uses SCRAM-SHA1 Authentication

The following example migrates a source replica set that uses SCRAM-SHA1 authentication to Atlas:

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username mySourceUser \
   --password mySourcePassword \
   --authenticationDatabase admin \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
   --destinationUsername myAtlasUser \
   --destinationPassword atlasPassw0Rd

To migrate from a source replica set that uses SCRAM-SHA1 authentication, run mongomirror with the following options:

• --host sourceReplSet/seed list of members

• --username sourceUser

• --password sourcePassword

• --authenticationDatabase sourceDatabase

• --destination Atlas Cluster

• --destinationUsername atlasUser

• --destinationPassword atlasPassword

The source replica set user must have the required access on source cluster. The backup role provides the appropriate privileges.

For the target, specify the replica set name followed by a seed list of members in the following format:

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

The specified user must have the Atlas admin on Atlas.

Migrate a Replica Set: Source Replica Set Requires X.509 Client Authentication

The following example migrates from a source replica set that uses X.509 authentication:

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry" \
   --authenticationDatabase '$external' \
   --authenticationMechanism MONGODB-X509 \
   --ssl \
   --sslPEMKeyFile <path-to-my-client-certificate.pem> \
   --sslCAFile <path-to-my-certificate-authority-certificate.pem> \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017 \
   --destinationUsername myAtlasUser \
   --destinationPassword atlasPassw0Rd

To migrate from a source replica set that uses X.509 authentication, run mongomirror with the following options:

• --host sourceReplSet/seed list of members

• --username subject from the client certificate

• --authenticationMechanism MONGODB-X509

• --authenticationDatabase '$external'

• --ssl

• --sslPEMKeyFile path-to-my-client-certificate.pem

• --sslCAFile path to root CA PEM file

• --destination Atlas Cluster

• --destinationUsername atlasUser

• --destinationPassword atlasPassword

The source replica set user must have the required access on source cluster. The backup role provides the appropriate privileges.

For the target, specify the replica set name followed by a seed list of members in the following format:

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

The specified user must have the Atlas admin on Atlas.

Migrate a Replica Set: Source Replica Set Requires Kerberos/GSSAPI Authentication

The following example migrates from a source replica set that uses Kerberos authentication:

mongomirror --host sourceRS/source-host1:27017,source-host2:27017,source-host3:27017 \
   --username sourceUser/administrator@MYREALM.COM \
   --authenticationDatabase '$external' \
   --authenticationMechanism GSSAPI \
   --destination myAtlasRS/atlas-host1:27017,atlas-host2:27017,atlas-host3:27017 \
   --destinationUsername atlasUser \
   --destinationPassword atlasPass

To migrate from a source replica set that uses Kerberos authentication, run mongomirror with the following options:

• --host sourceReplSet/seed list of members

• --username Kerberos user principal

• --authenticationDatabase '$external'

• --authenticationMechanism GSSAPI

• --destination Atlas Cluster

• --destinationUsername atlasUser

• --destinationPassword atlasPassword

The source replica set user must have the required access on source cluster. The backup role provides the appropriate privileges.

For the target, specify the replica set name followed by a seed list of members in the following format:

<replicaSetName>/<replicaMember>,<replicaMember>,<replicaMember>,...

The specified user must have the Atlas admin on Atlas.

Save mongomirror Output to a File

You can save the output logs from a mongomirror procedure to a file for later examination and debugging. Use the following format to save output to a mongomirror.log file:

mongomirror <args> 2>&1 | tee -a mongomirror.log

Previous version of documentation

Migrate with mongomirror

Mongomirror is End of Life (EOL) as of July 31st 2025, with mongosync taking its place. MongoDB will no longer provide any updates, security patches, or support of any kind. Mongosync provides significant enhancements in features, performance, and reliability compared to mongomirror. Please note that direct migration into Atlas with mongosync will only be supported for source cluster versions 5.0 and above. For other migration options, please refer to our self-managed tools. If you choose to use mongomirror past its EOL date, please note that mongomirror is only compatible with MongoDB 6.0 and below. Attempts to use mongomirror against newer versions may fail to connect or encounter other errors, which may or may not be silent.mongomirror is a tool for manually migrating data from an existing MongoDB replica set to a MongoDB Atlas replica set. See Download mongomirror.

mongomirror doesn't require you to shut down your existing replica set or applications, doesn't import user or role data, and doesn't copy the config database.

Use mongomirror for:

• Running a one-time migration of a dataset into a MongoDB Atlas cluster from a MongoDB deployment hosted outside of MongoDB Atlas.

• Running a one-time migration of a dataset from one Atlas cluster into another Atlas cluster.

See also Choosing a Data Import and Migration Tool.

Prerequisites

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 a Flex 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 7.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.

• Don't 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, include user credentials when running mongomirror. 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 or a Flex cluster.

• Can't be a Serverless instance (deprecated).

• 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.

  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.

Upgrade Path

mongomirror is not supported for migrations between MongoDB 6.0+ source clusters and 6.0+ destination clusters. You can't use mongomirror to migrate from a source replica set 6.0.x or later to a destination replica set 6.0.x or later.

You can use mongomirror to migrate from a source replica set on previous versions to a destination replica set with MongoDB version 6.0.

Alternatively, you can upgrade your source replica set to 6.0+ or 7.0+ and use this live migration procedure to migrate an upgraded replica set to Atlas.

mongomirror supports the following migration paths.

Download mongomirror

On macOS 64-bit, a security alert appears when you first try to open the mongomirror file after you have downloaded it. To proceed, see Open an app by overriding security settings.

mongomirror Process

When you start mongomirror, it:

1. Connects to Atlas over TLS (Transport Layer Security)/SSL (Secure Sockets Layer).

2. Performs an initial sync, copying collections from the existing MongoDB replica set to the destination cluster in Atlas.

3. After the initial sync, continuously tails the replica set's oplog for incoming changes and replays them on the destination cluster in Atlas. mongomirror doesn't copy the config database. mongomirror uses wire compression if you enable it on either the source or the destination cluster and use --compressors to specify which compression libraries to allow.

   mongomirror builds all indexes on the destination cluster in the foreground, regardless of how the indexes were built on the source cluster. Foreground index builds block all other operations on the database. To learn more, see Index Build Operations on a Populated Collection.

Once started, mongomirror runs continuously until you shut it down:

• If you shut down mongomirror during the initial sync stage, before you restart mongomirror, check that the destination cluster is empty, or run mongomirror with --drop.

• If you shut down mongomirror during the oplog tailing stage, the process stops tailing the oplog. You can restart mongomirror to continue tailing from the last processed oplog record using --bookmarkFile.

Run 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. For requirements, see Required Access on Source Replica Set.

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

In Atlas, go to the Database Access page for your project.

WARNING: Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

• If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.

• If it's not already displayed, select your project from the Projects menu in the navigation bar.

• In the sidebar, click Database Access under the Security heading.

  The Database Access page displays.

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:

• If it isn't already displayed, click the Database Users tab.

• Click Add New Database User.

• 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 (Virtual Private Cloud) peering, either the peer's VPC (Virtual Private Cloud) CIDR (Classless Inter-Domain Routing) block (or a subnet) or the Security Group of the peer VPC (Virtual Private Cloud).

In Atlas, go to the Clusters page for your project.

WARNING: Navigation Improvements In Progress We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

• If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

• If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

• If it's not already displayed, click Clusters in the sidebar.

  The Clusters page displays.

Click Connect.

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 user interface.

You don't need to use a driver to migrate data with mongomirror.

• From the Connect dialog box, click Shell.

• From the drop-down list, select 3.4 or earlier. The connection string should look similar to the following example. This example has been broken into multiple lines for readability:

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

• In a text editor, paste the value of replicaSet, add a forward slash (/), and then append the host list as comma-separated values, as shown in the following example:

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

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

Start mongomirror.

To complete the migration process, verify data transfer and switch to Atlas.

Switch to Atlas

After mongomirror completes the initial sync and tails the replica set's oplog, you can switch over to the destination Atlas cluster.

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.

Verify data transfer.

Verify that your data is transferred to the destination cluster using one of the following verification strategies. Use the following verification methods only after you ensure that the source or destination clusters are NOT writing data.

• Use the db.collection.countDocuments() method on each collection on the source and the destination clusters to obtain document counts and compare them between the clusters.

• Write a script that queries collections on the source cluster and then checks that the correct documents, indexes, collections, metadata, and views exist with the same values on the destination cluster. In the script, use the following commands on the source and destination clusters:

  • To verify the transfer of indexes and compare the results, use the db.collection.getIndexes() method.

  • To verify the transfer of metadata and compare the results, use the db.getCollectionInfos() method.

Update client applications to use the Atlas cluster.

Update your client applications with the Atlas connection string provided via the Connect button on the cluster panel.

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

Monitoring

mongomirror logs its progress to the standard output in the terminal. During the initial sync, mongomirror logs a progress bar for each collection it copies. For example:

2024-08-09T16:35:50.227-0000  [#....................]  park.events  2179/34184    (6.4%)
2024-08-09T16:35:50.227-0000  [#############........]  zoo.animals  29000/49778  (58.3%)

When tailing the oplog, mongomirror logs the lag time, in seconds, between the most recent oplog entry on the source cluster and the last processed oplog entry on the destination cluster. For example:

2024-12-12T16:22:17.027-0800 Current lag from source: 6s

A lag time of 6 seconds means that the last oplog entry mongomirror processed occurred 6 seconds before the most recent one available on the source cluster.

The amount of time it takes mongomirror to catch up may be greater or less than 6 seconds, depending on the number of entries that arrive per second.

A lag time of 0 seconds indicates that mongomirror is processing entries that arrived less than one second before the latest oplog entry.

If the source cluster has indexes, mongomirror builds the same indexes on the destination cluster. The progress log shows the start and end times of the index building process. To view the progress of the index builds, you can either:

• Use the currentOp command on the primary node of the destination cluster. The command field shows information about the running operation. Index building entries look similar to the following:

      "command" : {
             "createIndexes" : "perfs",
             "indexes" : [
                     {
                             "key" : {
                                     "animal" : "text"
                             },
                             "name" : "animal_text"
                     }
             ]...
  

• Download the mongodb logs for your destination cluster and search for recent entries for index-related lines. Log messages related to index building look similar to the following:

  {"t":{"$date":"2024-08-09T16:35:50.227+00:00"},"s":"I",  "c":"INDEX",    "id":20447,   "ctx":"conn1080","msg":"Index build: completed","attr":{"buildUUID":{"uuid":{"$uuid":"c4a62739-bf19-456d-bbd6-7baa29f1063b"}}}}
  

Performance

To avoid contention for network and CPU resources, run mongomirror on hosts other than your replica set's mongod instance hosts.

• mongomirror affects your source replica set's performance similar to having a secondary:

  • For the initial sync stage, the load scales with the size of your data set.

  • Once an initial sync completes, the load scales with oplog gigabytes used per hour.

Command Syntax, Options, and Examples

For mongomirror syntax, options, and examples, see the mongomirror reference page.

Troubleshooting

For mongomirror troubleshooting, see Common Post-Validation Errors for Live Migration (Pull).

In case you cannot connect to your destination because you're not using TLS, you can use the parameter --noTLS