Navigation

Migrate with mongomirror

On this page

mongomirror is a tool for manually migrating data from an existing MongoDB replica set to a MongoDB Atlas replica set. mongomirror does not require you to shut down your existing replica set or applications, and does not import user or role data or 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.

mongomirror supports the following migration paths:

Source Replica Set
MongoDB Version
Target Atlas Replica Set
MongoDB Version
5.0
4.4, 5.0
4.4
4.2, 4.4, 5.0
4.2
4.0, 4.2, 4.4, 5.0
4.0
3.6, 4.0, 4.2, 4.4, 5.0
3.6
3.6, 4.0, 4.2, 4.4, 5.0
3.4
3.6, 4.0, 4.2, 4.4, 5.0
3.2
3.6, 4.0, 4.2, 4.4, 5.0
3.0
3.6, 4.0, 4.2, 4.4, 5.0
2.6
3.6, 4.0, 4.2, 4.4, 5.0
Note

To downgrade from 4.4 to 4.2, 4.2 to 4.0, or 4.0 to 3.6, the source FCV must match the target.

Operating System
Download
Amazon Linux 1
Amazon Linux 2
ARM64 Ubuntu 16.04
ARM64 Ubuntu 18.04
ARM64 Ubuntu 20.04
Debian 10
Debian 8.1
Debian 9.2
macOS 64-bit
PPC64LE RHEL 7.1
PPC64LE RHEL 8.1
PPC64LE Ubuntu 16.04
PPC64LE Ubuntu 18.04
RHEL 6.2
RHEL 7.0
RHEL 8.0
s390x RHEL 8.0
SLES 12
SLES 15
Ubuntu 14.04
Ubuntu 16.04
Ubuntu 18.04
Ubuntu 20.04
Windows

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:

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" ]
    }
    )

The target Atlas deployment:

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.

When you start mongomirror, it:

  1. Connects to Atlas over TLS/SSL.
  2. Performs an initial sync, copying collections from the existing MongoDB replica set to the target cluster in Atlas.
  3. After the initial sync, continuously tails the replica set's oplog for incoming changes and replays them on the target cluster in Atlas. mongomirror does not copy the config database. As of version 0.9.0, mongomirror uses wire compression if you enable it on either the source or the target cluster and use --compressors to specify which compression libraries to allow.

    Note

    Starting in version 0.5.0, mongomirror builds all indexes on the target 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:

1

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.

2

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.

3

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 Security Group of the peer VPC.
4
  1. Click Database in the top-left corner of Atlas.
  2. From the Database Deployments view, click Connect for the Atlas cluster into which you want to migrate data.
5

You can get your Atlas cluster's hostname information from the Atlas user interface.

Note

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

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 --destination in the next step.

6

Start mongomirror with the following options:

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.

To complete the migration process, switch to Atlas.

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

1

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

2

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

3

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

4

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.

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:

2016-12-16T17:54:53.638-0800 [#....................] park.events 2179/34184 (6.4%)
2016-12-16T17:54:53.638-0800 [#############........] 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 target cluster. For example:

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

Note

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 target 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 target cluster. The command field shows information about the running operation. Index building entries look similar to the following:

    "command" : {
    "createIndexes" : "perfs",
    "indexes" : [
    {
    "key" : {
    "workTitle" : "text"
    },
    "name" : "workTitle_text"
    }
    ]...
  • Download the mongodb logs for your target cluster and search for recent entries for index-related lines. Log messages related to index building look similar to the following:

    2018-11-29T16:58:25.018-0800 I INDEX [conn1] build index on: example.airlines properties: { v: 2, key: { airline: 1.0 }, name: "airline_1", ns: "example.airlines" }

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.

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

Give Feedback

On this page