Migrating Data Into mLab

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

  1. 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
  2. Must be running as a replica set
  3. Must be able to supply mLab with an admin database user that has least the privileges of the backup role
  4. Must be able to allow inbound network access from a mLab-hosted deployment

High-level Migration Steps

  1. 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.
  2. Supply mLab with the credentials for a admin database user that has at least the privileges of the backup role.
  3. 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.
  4. You will confirm that you can connect and authenticate to your new mLab-hosted deployment.
  5. 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

  1. Must be running version 2.6.x+, 3.0.x, 3.2.x, or 3.4.x
  2. Must be running as a replica set
  3. If running in “auth” mode, must be able to supply mLab with the replica set’s key file (the value for the --keyFile option)
  4. Must be able to allow network access from and to a mLab-hosted deployment

Using mongodump / mongorestore

MongoDB’s mongodump and mongorestore utilities are command-line tools that provide fine-grained data export and import capabilities. To download these utilities visit the MongoDB download page.

When you are ready to copy data from one MongoDB instance to another, follow these instructions:

  1. Log in to the mLab management portal.
  2. If you have not already done so, create a new mLab deployment as your “target” instance.
  3. To prevent data inconsistency, stop any processes running against your source instance.
  4. In a terminal window, create a backup of your source instance using the mongodump command.
  5. Use the mongorestore command to import your backup into your new instance.
  6. 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.

  1. Log in to the mLab management portal.
  2. If you have not already done so, create a new mLab deployment to host the destination database.
    • The destination database itself does not need to be created; the command will implicitly create it if it does not exist.
  3. If you have not already done so, create an admin database user for the destination deployment.
  4. To prevent data inconsistency, stop any processes running against your source database.
  5. In a terminal window, connect to the destination instance using the admin database user’s credentials.
  6. Run the db.copyDatabase() helper method.
    • 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..
  7. 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:

  1. Log in to the mLab management portal.
  2. If you have not already done so, create a new mLab database as your “target” database.
  3. Use the mongoimport command to import your text file(s) into your new database.

Example 1: Command to import a JSON file

% mongoimport -h ds012345.mlab.com:56789 -d dbname -c collectionname -u dbuser -p dbpassword --file filename.json

Example 2: Command to import a CSV file

% mongoimport -h ds012345.mlab.com:56789 -d dbname -c collectionname -u dbuser -p dbpassword --file filename.csv --type csv --headerline 

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:

  1. Log in to the mLab management portal.
  2. From your account’s Home page, navigate to the deployment with the database that you are going to import or export.
    • If necessary, navigate to the desired database after navigating to the deployment.
  3. Click the “Tools” tab.
  4. Click the “import/export” link and find the command you want to use. img-importexport
  5. Replace all placeholders (i.e., the values enclosed in angled brackets).
  6. In your terminal window, run the adjusted command.


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.