Guide to Migrating a Sandbox Heroku Add-on 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 mLab Heroku add-on to MongoDB Atlas.

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

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

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 and project(s)

  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.
  4. (Optional) Rename the default project.
    • We recommend creating separate projects for your various environments (e.g., production, test, development). We advise against mixing development and production clusters within the same project since they share security-related resources such as database users and IP whitelists.
    • Common project names are “<your app’s name> Production” and “<your app’s name> Development”.
    • Note that if you want to have multiple Atlas free-tier (M0) clusters, they will need to be in separate Atlas projects.
    • You’ll later be able to manage access to your project(s).
  5. (Optional) Create multiple projects within your Atlas organization.

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 Heroku add-ons to migrate, 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.

Steps:

  1. Log 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.

The “mLab Account” link in the left navigation pane should now be highlighted, and you should see the “mLab Account” view. This view lists your mLab deployments on the “Deployments” tab and lists your mLab account users on the Account Users tab. This view makes it easier to invite your mLab account users to your Atlas organization and to migrate your mLab deployment(s) to Atlas.

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. Log in to the target Atlas organization.
  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. Navigate to the Organization Home view (click on the green MongoDB leaf icon in the upper-left corner).
  4. From the left navigation select “mLab Account”.
  5. Locate the mLab 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

Create or select the Atlas project to which you will migrate the source mLab database.

Step 2. Import database user(s)

img-screenshot-heroku-sandbox-db-users

Step 3. Configure an IP whitelist

img-screenshot-heroku-sandbox-whitelist

Step 4. Create the target Atlas cluster

img-screenshot-heroku-sandbox-cluster

Step 5. Confirm the source and target

Review info about the source and target to confirm that you’re migrating from and to the correct deployments.

Step 6. Test the migration

Perform a test migration. Note that:

Step 7. 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-atlas-test-connectivity

Step 8. Ensure independence from the Heroku add-on’s config var

When you are done migrating your Sandbox mLab Heroku add-on to Atlas, you will be deleting the Heroku add-on. Deleting the Heroku add-on will not only delete your mLab database but it will also delete the Heroku config var that was automatically created when you provisioned the Heroku add-on.

As such, it’s critical that you switch to a new Heroku config var before starting the migration process.

  1. Copy and paste the value of the existing config var into a brand-new config var (e.g., called “DB_URI”).
    • The existing config var that was automatically provisioned should look like “MONGODB_URI” or “MONGOLAB_URI” or “MONGOLAB_<color>_URI”.
  2. Change your application code such that it no longer uses the original config var and now uses the new config var.
  3. Redeploy your Heroku app with the code change.

mLab Heroku Add-on FAQs

How do I know whether my Heroku app is dependent on a Heroku add-on config var?

  1. Log in to Heroku
  2. Select your app
  3. On the “Resources” tab, you’ll see a list of the Heroku add-ons for this app, including the “mLab MongoDB” ones.
  4. For each “mLab MongoDB” add-on, you’ll see “Attached as MONGODB” or “Attached as MONGOLAB” or “Attached as “MONGOLAB_<color>”. Append “_URI” to that string to get the corresponding Heroku config var name (see screenshots below).
  5. Search in your application code for usage of an environment variable by the config var’s name.

Screenshot from Heroku app’s “Resources” tab:

img-heroku-resources-addons

Screenshot from Heroku app’s “Settings” tab:

img-heroku-config-vars

What if I am using Nightscout with an mLab Heroku add-on?

Please follow our guide for migrating a Nightscout Sandbox Heroku Add-on to Atlas instead of using this one.

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 restart your application with the connection string for your Atlas cluster.

Step 11. Delete mLab deployment (instructions only)

To delete the source mLab deployment, you will need to delete the Heroku mLab add-on via Heroku’s interface.

Deleting your Heroku mLab add-on will also delete the config variable that was automatically created when the add-on was first created (e.g., “MONGODB_URI” or “MONGOLAB_URI”). Ensure that you completed the step to ensure independence from the Heroku add-on’s config var before deleting the Heroku mLab add-on.