Migrate with mongomirror
¶
mongomirror
is a utility for 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.
mongomirror
is intended to be used as a utility for performing
a one-time migration of a dataset into a MongoDB Atlas cluster from a MongoDB
deployment hosted outside of MongoDB Atlas. It can also be used for performing
a one-time migration of a dataset from one Atlas cluster into another Atlas
cluster. Any other use of this utility is not supported.
mongomirror
does not import user/role data.
Download mongomirror
¶
Operating System | Download |
---|---|
Amazon Linux 1 | mongomirror-linux-x86_64-enterprise-amzn64-0.11.0.tgz |
Amazon Linux 2 | mongomirror-linux-x86_64-enterprise-amazon2-0.11.0.tgz |
Debian 8 | mongomirror-linux-x86_64-debian81-0.11.0.tgz |
Debian 9 | mongomirror-linux-x86_64-debian92-0.11.0.tgz |
macOS | mongomirror-osx-x86_64-0.11.0.tgz |
RHEL 6.2 | mongomirror-linux-x86_64-rhel62-0.11.0.tgz |
RHEL 7.0 | mongomirror-linux-x86_64-rhel70-0.11.0.tgz |
Suse 12 | mongomirror-linux-x86_64-suse12-0.11.0.tgz |
Ubuntu 14.04 | mongomirror-linux-x86_64-ubuntu1404-0.11.0.tgz |
Ubuntu 16.04 | mongomirror-linux-x86_64-ubuntu1604-0.11.0.tgz |
Ubuntu 18.04 | mongomirror-linux-x86_64-ubuntu1804-0.11.0.tgz |
Windows | mongomirror-win32-x86_64-0.11.0.zip |
Prerequisites¶
Source¶
- The source MongoDB deployment must be a replica set. If the source is
a standalone MongoDB deployment, convert to a replica set first to
use
mongomirror
. See Convert a 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 Tier) orM2/M5
shared cluster. - You should not change the
featureCompatibilityVersion
flag at any time during the procedure. You should not 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.Contact MongoDB Support if you believe renaming or dropping a collection needs to occur during the migration process. From the Atlas UI, click Support to open a support ticket.
Required Access on 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 theadmin
database covers this requirement. - Read the oplog.
- 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 execute the appropriate commands in the
mongo
shell:
For source clusters running MongoDB version 3.4 or later a user must have, at a minimum, both
clusterMonitor
andreadAnyDatabase
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
andreadAnyDatabase
roles, as well as read access on thelocal
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¶
- The target Atlas cluster must be a replica set.
The target Atlas cluster should not contain any namespaces that overlap with the source cluster. If
mongomirror
detects overlapping namespaces on the target cluster it errors out before the migration process begins. If your target cluster contains overlapping namespaces, you can either:- Run
mongomirror
with the--drop
option to delete all non-system data from the target cluster, or - Use the
--includeNamespace
option to specify particular namespaces to import from the source cluster.
- Run
- The target Atlas cluster cannot be an
M0
(Free Tier),M2
, orM5
shared cluster. - The target Atlas cluster MongoDB version must be the same as or later than the source cluster MongoDB version.
- You should not change the
featureCompatibilityVersion
flag at any time during the procedure. mongomirror
is not compatible with TTL indexes. Drop any existing TTL indexes and rebuild them when the migration process is complete.
Procedure¶
Set up database user in 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 (i.e.
readAnyDatabase
on theadmin
database) - Read the oplog.
- 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 execute the appropriate commands in the
mongo
shell:
For source clusters running MongoDB version 3.4 or later a user must have, at a minimum, both
clusterMonitor
andreadAnyDatabase
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
andreadAnyDatabase
roles, as well as read access on thelocal
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" ] } )
Make note of the username and password for this user, as you must
specify these credentials when running mongomirror
.
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:
- In the Security section of the left navigation, click Database Access. The Database Users tab displays.
- 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 peering, either the peer's VPC CIDR block (or a subnet) or the peer VPC