Migrating from an existing MongoDB deployment

There are several different ways to migrate data into mLab. The method you choose depends on your particular data source and your uptime requirements.

If you have any questions about which process makes the most sense for your application, don’t hesitate to contact support@mlab.com for help.

Use mLab’s migration tool

Not available for Sandbox databases. Feature currently in Preview.

If you are currently running a MongoDB instance that you would like to migrate over to a mLab-hosted deployment, you have the option to migrate with almost no downtime using mLab’s migration tool.

Pre-requisites for Source Deployment

Must be running version 2.6.x, 3.0.x, 3.2.x, or 3.4.x

Some restrictions apply if running 2.6.x but < 2.6.10

Must be running as a replica set

Must be able to supply mLab with an admin database user that has least the privileges of the backup role

Must be able to allow inbound network access from a mLab-hosted deployment

High-level Migration Steps

Create your new deployment on mLab.

If you’re migrating into one of our Dedicated plans, we recommend creating a larger plan than you think you’ll end up on to help with the initial bulk load. We pro-rate charges by the day and downgrades are seamlessly on our Dedicated Cluster plans via our rolling node replacement process.

If you would like some help sizing your new deployment, please ask support@mlab.com for help.

Supply mLab with the credentials for a admin database user that has at least the privileges of the backup role.

mLab will start the migration process and inform you when your mLab-hosted deployment is fully in-sync with your existing deployment.

The migration tool will take an initial copy of your deployment and restore it into your mLab-hosted deployment.

After that it will keep up-to-date with your deployment by tailing the source deployment’s oplog.

You will confirm that you can connect and authenticate to your new mLab-hosted deployment.

When you are ready to finalize the migration to mLab:

You will stop writes to your application.

You will roll out a connection string change.

Contact support@mlab.com for more details on this migration method and/or if you’d like to get started.

Do not execute writes against the target deployment until the migration is complete or else there could be data integrity problems.

Using replica set replication

Available for Dedicated plans only.

If you are currently running a replica set that you would like to migrate over to one of mLab’s Dedicated plans, you have the option to minimize downtime by using MongoDB’s internal replication mechanisms.

Pre-requisites for the source deployment

Must be running version 2.6.x+, 3.0.x, 3.2.x, or 3.4.x

Must be running as a replica set

If running in “auth” mode, must be able to supply mLab with the replica set’s key file (the value for the --keyFile option)

Must be able to allow network access from and to a mLab-hosted deployment

When the restoration has completed and you have updated your application with the new connection URI, you can start writing to your new instance.

To minimize the possibility of error, the versions of your target database, source database, and mongodump/mongorestore utility should match. For example: use mongodump 3.0 to restore a backup taken from MongoDB 3.0 into a MongoDB 3.0 database.

Note that the version of your mongodump/mongorestore utility must match the version of MongoDB you have deployed. If you have multiple MongoDB versions installed, be sure to use the correct one.

Using copydb

Available for Dedicated plans only

MongoDB’s copydb command allows you to copy a database directly from a remote, source instance to the current, destination instance.

This method is faster than mongodump/mongorestore, but you must have a Dedicated plan with mLab in order to run this command, since it requires full administrative privileges on the destination instance.

The expected order of arguments is somewhat confusing so take caution as you construct the command.

The duration of the copy process can vary widely, depending on the amount of data, number of indexes, network latency, etc..

When the copying has completed and you have updated your application with the new connection URI, you can start writing to your new database.

If you have SSL enabled on your deployment, note that copydb will not work unless the remote source also supports SSL.

Importing a JSON, CSV or TSV file

If you need to import or export data in a flat file (non-binary) format such as JSON, CSV, or TSV, the mongoimport and mongoexport commands are the appropriate MongoDB command-line tools to use. To download these utilities, visit the MongoDB download page.

Once MongoDB is installed successfully, follow the instructions below to import a JSON, CSV, or TSV file into your mLab-hosted database:

The first row of the CSV input file must specify the field names; each subsequent line in the file must represent a single document.

The --headerline option in the command is what tells mongoimport to interpret the first line of the CSV file as the field names and not as a document.

For a TSV file, all of the above also applies, the only difference is that --type tsv should replace --type csv in the command.

Pre-filled import/export command-line strings

MongoDB commands can be tricky to write and typos aren’t any fun so we’ve tried to make it easier for you by constructing pre-filled command-line strings that you can copy and paste directly into your terminal. To obtain these strings, follow these instructions:

The strings provided in the tool are basic and do not include many of the extra options associated with the MongoDB commands. You may need to adjust the strings further, depending on which options you desire to use.