Guide to Migrating a mLab Sandbox (impacted by the shutdown of mLab’s Heroku add-ons) 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 mLab Sandbox mLab that was impacted by the shutdown of mLab’s Heroku add-ons to MongoDB Atlas.

Nightscout users with Sandbox mLab Heroku add-ons - please follow our guide for migrating a Nightscout Sandbox to Atlas.

If you are migrating a for-pay deployment or are not migrating a Heroku add-on, please see our general migration guide.

For background please visit the Shutdown of mLab’s Heroku Add-on on November 10, 2020.

Migration Prerequisites

Ensure the ability to log into your mLab account as the mLab account admin user:

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.

When you created your mLab Heroku add-on, that process automatically created an account at mLab for you with an account name prefixed with “heroku_”. This means that if you have multiple mLab Heroku add-ons, you have multiple mLab accounts.

If you have multiple mLab accounts belonging to the same company and would like to migrate them to the same target Atlas organization, you will first connect the target Atlas organization to one source mLab account. Then at any point you can disconnect and then connect the same target Atlas organization to a different source mLab account. There are no restrictions to the number of times you can disconnect and connect to different source mLab accounts. This can all be done using the “Connect to mLab” and “Disconnect from mLab” buttons in the “Organization Settings” page for your 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 an example of what the migration wizard looks like when migrating from an mLab Sandbox database to an Atlas M0 cluster.

img-screenshot-heroku-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-heroku-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-heroku-sandbox-db-users

Step 3. Configure an IP whitelist

Make sure the checkbox to allow all IP addresses is checked 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-heroku-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-heroku-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-heroku-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.

Step 7. Test the migration

Perform a test migration. Note that:

Step 8. Test connectivity

If you can’t log in to your Heroku dyno, 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. Most mLab-hosted deployments used by Heroku apps allow all IP addresses since Heroku IP addresses are, in general, highly dynamic.

img-screenshot-heroku-sandbox-test-connectivity

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-heroku-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 change your Heroku application to use the connection string for your Atlas cluster.

Normally, the connection string to your MongoDB database is stored in a Heroku config var (e.g. or “MONGODB_URI” or “MONGODB__URI" or "MONGOLAB_URI") that was created when the Heroku mLab add-on was provisioned. The config var was likely removed when the add-on was deleted during the shutdown. If your application is using it to connect to your database (you can search in your application code for usage of an environment variable by the config var’s name), re-create/re-configure the Heroku config var using the "Settings" tab for your Heroku application's dashboard and set the value of the Heroku config var to the connection string to your Atlas cluster.

If you do not know the password for your database users, you can change the password for your database users.

img-heroku-settings-config-vars

Step 11. Delete mLab deployment (instructions only)

To delete the source mLab database, you will need to click on the “Delete database” button while logged into the mLab UI. You will continue to receive notifications from mLab if you do not delete your mLab deployment.