Guide to Migrating a Sandbox database to Atlas

This page provides a list of the prerequisites for migrating an mLab free Sandbox database to MongoDB Atlas. It also provides a step-by-step guide to migrating a free Sandbox database from mLab to MongoDB Atlas.

If you are migrating a Heroku add-on, a for-pay deployment, or are using Nightscout, please see our FAQ on how to migrate for links to our other step-by-step guides and our demo videos.

Migration Prerequisites

Ensure minimum required versions:

Review key differences between mLab and Atlas:

Immediately before starting to migrate a specific mLab deployment to Atlas:

Pre-Migration Setup

A. Create your Atlas organization

  1. Visit https://mongodb.com/cloud/atlas/signup and register for an Atlas account.
    • The email address that you sign up with will become the username that you use to log in.
  2. Ensure that you are on the Project view by visiting https://cloud.mongodb.com.
  3. (Optional) Rename the default organization.
    • If you will be using this account on behalf of a company, rename it to the name of the company.
    • You will be able to change this later so don’t worry about what you choose.
  4. (Optional) Delete the Atlas project that was automatically created during registration.
    • An Atlas project called “Project0” was automatically created in Step 1 and can optionally be deleted since it won’t be used.

B. Connect your Atlas organization to the source mLab account

In order to use the migration tool that was custom-built for migrations from mLab to Atlas, you’ll need to create a connection between the source mLab account (the account from which you want to migrate deployment(s)) to the target Atlas organization.

Steps:

  1. Ensure that you are logged in to the target Atlas organization as an Atlas Organization Owner.
    • Only the Organization Owner will be able to establish a connection to the source mLab account. However, this root-level access is not required for migrating; any Atlas user that is a Project Owner of the target Atlas project can migrate a specific deployment from mLab.
  2. Ensure that the target Atlas organization has been selected from the Organizations menu (the drop-down menu in the top-left corner next to the MongoDB green leaf logo).
  3. Click on the Organization Settings icon next to the Organizations menu (the gears icon). img-atlas-org-settings.
  4. Click on the green “Connect to mLab” button.

  5. Log in to the source mLab account from the same browser as the mLab Admin User.
  6. In mLab’s UI review the text presented by the “Authorize MongoDB Atlas” form and click “Authorize” to complete the connecting of your mLab account with your Atlas organization.
  7. The “mLab Account” link in the left navigation pane should now be highlighted, and you should see the “mLab Account” view which provides access to the migration wizard.

If you’ve navigated away from this “mLab Account” view you can return back at any time by navigating to the Organization Home view (click on the green MongoDB leaf icon in the upper-left corner) and then clicking on the “mLab Account” link.

Migrating a Specific Database

After reviewing the migration prerequisites detailed above and completing the pre-migration setup steps, perform the following steps to migrate a specific mLab deployment.

C. Initiate the migration process for a specific database

Steps:

  1. Ensure that you are on the “mLab Account” view and seeing a list of your mLab deployment(s). If you are not on this view:
    • Ensure that you are logged in to the target Atlas organization.
    • Ensure that the target Atlas organization has been selected from the Organizations menu (the drop-down menu in the top-left corner next to the MongoDB green leaf logo).
    • Navigate to the Organization Home view (click on the green MongoDB leaf icon in the upper-left corner).
    • From the left navigation select “mLab Account”.
  2. Locate the mLab Sandbox deployment that you want to migrate to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Configure Migration” to open the migration wizard for the given deployment.

Below is a screenshot example of what the migration wizard looks like in the Atlas UI when migrating from an mLab Sandbox database to an Atlas M0 cluster.

img-screenshot-sandbox-checklist

D. Complete the tasks in the migration wizard

Step 1. Set the target Atlas project

Enter a value in the “Project Name” field (e.g., “development”) and then click on the green “Confirm Project and Continue” button. You will be able to change the name of the project later.

img-screenshot-sandbox-create-project

Step 2. Import database user(s)

Click on the green “Import Database Users and Continue” button to import any database users that exist on the source mLab database.

If the target Atlas project already has existing database user(s), this step will only provide instructions on how to manually create database users.

img-screenshot-sandbox-db-users

Step 3. Configure an IP whitelist

Check the checkbox to allow all IP addresses and then click on the green “Allow All and Continue” button.

You will receive an email from MongoDB Atlas with subject of ‘You’ve added “Allow access from anywhere (0.0.0.0/0)” to your IP Whitelist’. This is expected.

img-screenshot-sandbox-whitelist

Step 4. Create the target Atlas cluster

Select “Create most equivalent new cluster” from the drop-down menu. This will expand the modal into a larger screen.

Scroll down and click the green “Confirm Target and Continue” button to create a free Atlas database (M0 tier). It will take about 7-9 minutes for the Atlas database to be created.

Unlike mLab, the Atlas M0 (free) tier does not include backups. If backups are important to you, you will need to manually take your own backups (email support@mlab.com for help) or migrate to the Atlas M2 tier which is approximately $9 per month and includes a free daily backup.

img-screenshot-sandbox-cluster

Step 5. Review validation warnings

The migration checklist will display relevant validation warnings in note boxes. Carefully review these before continuing with next steps.

img-screenshot-sandbox-validation-warnings

Step 6. Confirm the source and target

Review info about the source and target to confirm that you’re migrating from and to the correct deployments. If everything looks good, click on the green “Confirm and Continue” button.

img-screenshot-sandbox-confirm

Step 7. Test the migration

Perform a test migration. Note that:

Step 8. Test connectivity

img-screenshot-sandbox-test-connectivity

If you cannot log in to your application server (e.g., if your app is running on Heroku), you can perform these tests from any machine as long as you have whitelisted 0.0.0.0 (all IP addresses) on the “Network Access” page for the target Atlas project. mLab Sandbox databases always allow all IP addresses.

Step 9. Migrate

This step is the real migration! Clicking “Begin Migration” will change the role of the database user(s) which exist on the source mLab deployment to be read-only.

If an unexpected error occurs, and you want to abort the migration process and start using your source mLab deployment again, you will need to recreate the database user(s) on your source mLab deployment through mLab’s management portal. Performing a test migration and testing connectivity ahead of time will help avoid the need to do this.

If you do rollback to mLab, note that any writes that are made to the target Atlas cluster will not exist on the source mLab deployment and will be deleted if you attempt another migration later.

img-screenshot-sandbox-migrate

Step 10. Start using Atlas

At this point the import of data and indexes from your source mLab database to the target Atlas cluster is complete.

You can now restart your application with the connection string for your Atlas cluster. When your application client(s) are exclusively reading and writing from the target Atlas cluster, click on the green “I’m Done” button.

img-screenshot-sandbox-start-using-atlas

Step 11. Delete mLab deployment (instructions only)

To delete the source mLab database, you will need to delete it while logged into the mLab UI.