Guide to Migrating to Atlas

This page provides a list of the prerequisites for migrating to Atlas and a step-by-step guide to the migration process.

For details on migration timing and our FAQ please visit https://docs.mlab.com/mlab-to-atlas/.

Migration Prerequisites

Ensure minimum required versions:

Review key differences between mLab and Atlas:

Ensure that all recurring query patterns are well-indexed and that your deployment is running healthy on mLab:

Consider enabling SSL on your mLab deployment before migrating:

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

Pre-Migration Setup

A. Create your Atlas organization and project(s)

If you will be using Atlas on behalf of a company, note that you will only need a single Atlas organization. Unlike mLab, MongoDB Atlas provides the ability to have multiple Organization Owners and to assign fine-grained privileges to users.

  1. Visit https://mongodb.com/cloud/atlas 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.
  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.

If you have multiple mLab accounts that belong to the same company, note that you can 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. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. From the left navigation select “Settings”.
  4. On the “General Settings” tab, click on the “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” tab 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. From the Context menu ensure that the organization is selected and in the left navigation pane click on the “mLab Account” link.

C. Configure payment method or apply prepaid credits (not required for free databases)

In order to create a for-pay Atlas cluster (M2 or above), you will either need to configure a payment method or apply prepaid credits (from an annual contract).

mLab’s service and MongoDB Atlas’ service are completely separate which means that even if you already have a credit card attached at mLab, you’ll need to supply it to MongoDB Atlas as well.

Configure Credit Card or PayPal

Steps:

  1. Log in to the target Atlas organization.
  2. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. From the left navigation select “Billing”.
  4. Click the “Edit” button in the “Payment method” panel.

Apply Prepaid Credits

Steps:

  1. Log in to the target Atlas organization.
  2. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. From the left navigation select “Billing”.
  4. Click the “Apply Credit” button and enter the activation code that you received via email.

D. (Optional) Invite the source mLab account’s users to your Atlas organization and grant project access

After the connection between the source mLab account and the target Atlas organization has been established you will be able to see a list of the account users which exist on the source mLab account and have the opportunity to invite a given mLab user’s email address to your Atlas organization.

Unlike with mLab, a given email address (and username) on Atlas can be associated with many Atlas organizations.

Steps:

  1. Navigate to the “mLab Account” view.
    • From the left navigation click “mLab Account”.
  2. Select the “Account Users” tab.

  3. Open the “Invite mLab User to Organization” dialog.
    • Locate the user that you want to invite to the target Atlas organization.
    • Click the ellipses (…) button for that user.
    • Click “Invite User”.
  4. In the dialog, click “Send Invitation”.
    • The dialog will close and Atlas will send an email to that user’s email address inviting them to the Atlas organization. The subject of this email will start with “Invitation to MongoDB Cloud”.
    • If this email address is new to Atlas (i.e., isn’t associated with an existing Atlas user), when the invitation is accepted, this email address will become the username for the new Atlas user. This new Atlas user will only be able to log into Atlas and not mLab.
    • Otherwise when the invitation is accepted, this user will now see your Atlas organization associated with their profile.
  5. Ensure that the correct target project is selected.
    • From the “Context” menu in the top-left corner select a specific project.
  6. Grant access to the target project.
    • View Atlas documentation on managing project access and project roles.
    • The Atlas user that initiates a migration into a target Atlas cluster needs to have “Project Owner” access.

Migrating a Specific Deployment

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

D. Initiate the migration process for a specific deployment

Steps:

  1. Log in to the target Atlas organization.
  2. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. From the left navigation select “mLab Account”.
  4. 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 checklist for the given deployment.

F. Complete the tasks in the migration checklist

Migration checklist tasks include:

Post-Migration Atlas Configuration Review

G. Select a support plan for your Atlas organization

By default Atlas organizations include only a Basic Support plan which does not include database support or a response time SLA. Unlike on mLab, in order to get support for your database you need to purchase an Atlas support plan separately.

When you migrate from mLab to any for-pay Atlas cluster, you will be presented with the option to select one of the two types of Atlas support plans below.

The price of Atlas support plans are determined by monthly usage costs, which are the sum of cluster (VM/disk), data transfer, and backup costs.

Our intent is that your all-in Atlas costs do not exceed what you’re paying at mLab. As such, when you migrate your source mLab deployment to Atlas, the migration tool may present you with an option to select Developer Support or Premium Support at a discount.

Developer Support

If you are in development or are running a non-critical application, the Developer Support plan is a great choice. This plan has been designed to provide in-depth technical support but with slower response times.

Premium Support

If your application(s) have demanding uptime and/or performance requirements, we highly recommend a Premium Support plan. These plans are designed to provide high-touch, in-depth technical support for advanced issues such as performance tuning, as well as rapid response times for emergencies, 24x7.

img-atlas-support-plans

If you have questions please email support@mlab.com for help.

H. Customize the backup policy for your Atlas cluster (M10+)

We recommend reviewing the backup schedule and retention policy for your target Atlas cluster.

Be aware that:

View Atlas documentation on Snapshot Scheduling and Retention Policy.

I. Test failover and ensure resilience (M10+)

Atlas performs maintenance periodically. This maintenance can happen at any time unless you’ve configured a maintenance window. To ensure that maintenance on Atlas is seamless for your application(s):

  1. Configure your application(s) to use the exact connection string published in Atlas’ UI.
  2. Test failover on Atlas.
  3. (Optional) Configure a maintenance window for your Atlas project.

Reference

Configuring Database users and the IP Whitelist

Unlike with mLab, different Atlas clusters can share the same database users and network configuration. Specifically, be aware that Atlas clusters within a given Atlas project share the same database users and whitelisted IP addresses.

MongoDB (Database) Users

To access the Atlas cluster, you must authenticate using a MongoDB User that has access to the desired database(s) on your Atlas cluster. You can configure database users by selecting “Database Access” in the left navigation for your project. On Atlas, database users are separate from Atlas users just as on mLab, database users are separate from mLab users.

View Atlas documentation on configuring MongoDB users.

mLab admin database users have the root role on the admin database. The Atlas privilege that is most equivalent is Atlas admin but be aware that this privilege does not have all the permissions that mLab admin database users have.

Configuring the IP Whitelist

IP Whitelist

To access your target Atlas cluster, you’ll need to ensure that any necessary whitelist entries have been created.

Atlas is different than mLab in that you must configure IP whitelist entries in order to connect to an Atlas cluster. To access the Atlas cluster, you must connect from an IP address on the Atlas project’s IP whitelist. You can configure IP whitelist entries by selecting “Network Access” from the left navigation for your Atlas project.

Note that mLab’s Sandbox and Shared plan deployments are always accessible by all IP addresses. To match the firewall settings of your mLab Sandbox or Shared plan deployment you can whitelist all IP addresses (0.0.0.0/0) on your Atlas cluster. However, we recommend whitelisting only the addresses that require access. To match the firewall settings of your mLab Dedicated plan deployment on Atlas you can review your current mLab firewall settings on the “Networking” tab in mLab’s UI.

View Atlas documentation on configuring whitelist entries.

Sizing the Target Atlas Cluster

The Atlas M0, M2, and M5 plans run on shared resources (VM/disk) while the Atlas M10 plans and above run on dedicated resources.

mLab Plan Suggested Atlas Tier
Sandbox M0 (free) or M2
Shared M2, M5, or M10
Dedicated M10 and above

mLab Sandbox

If your deployment is running on a mLab Sandbox (free) plan, you may migrate to the Atlas M0 (free tier).

However note that:

mLab Shared

If your deployment is currently running on an mLab Shared plan, the tier that we suggest on Atlas depends on the size of your database.

mLab Size 1 Suggested Atlas Tier  
Less than 1.6 GB M2 Review warnings below
Between 1.6 GB and 4 GB M5 Review warnings below
More than 4 GB M10 Ensure CPU usage will not be too high

Atlas M2/M5 Warnings:

Atlas M10 Warning:

The Atlas M10 tier (which is similar to mLab’s M1 tier) has just 1 CPU core.

As such before migrating from an mLab Shared plan to the Atlas M10 make sure that you visit the mLab “Slow Queries” tab to view and build the indexes recommended by mLab’s Slow Queries Analyzer. If the “Slow Queries” tab continues to show a high rate of slow operations, please email support@mlab.com for help before attempting to migrate to Atlas.

mLab Dedicated

If your deployment is currently running on an mLab Dedicated plan, the following table shows the equivalent Atlas tier.

Note that Atlas sets limits for concurrent incoming connections based on instance size.

mLab Plan Equivalent Atlas Tier
M1 Standard or High Storage M10
M2 Standard or High Storage M20
M3 Standard or High Storage M30
M4 Standard or High Storage M40 (General class)
M5 Standard or High Storage M50 (General class)
M6 Standard or High Storage M60 (General class)
M7 Standard or High Storage M80 (Low-CPU)
M8 Standard or High Storage M200 (Low-CPU)
   
M3 High Performance (legacy) M40 (Local NVMe SSD)
M4 High Performance (legacy) M40 (Local NVMe SSD)
M5 High Performance M50 (Local NVMe SSD)
M6 High Performance M60 (Local NVMe SSD)
M7 High Performance M80 (Local NVMe SSD)

Choosing the Atlas disk type and size (M10 and above)

AWS

mLab’s Dedicated Standard and High Storage plans use AWS’s General Purpose SSD (gp2) EBS volumes. By default Atlas uses the same volume type.

The performance of this volume type is tied to volume size. As such when you create your cluster on Atlas:

Google Cloud Platform (GCP) and Azure 2 (AZR2)

mLab’s Dedicated plans on GCP and Azure 2 use the same disk type as Atlas. On GCP both use GCP’s SSD Persistent Disks. On Azure both use Premium SSD Managed Disks.

The performance of these disk types is tied to disk size. As such when you create your cluster on Atlas:

Azure Classic (AZR)

mLab’s Azure Classic Dedicated plans use magnetic disks (Azure’s page blobs and disks) while Atlas uses Premium SSD Managed Disks.

Disk I/O will be significantly improved on your target Atlas cluster. As such when you create your cluster on Atlas:

Operational Limitations of the Atlas M0, M2, and M5 tiers

The Atlas M0 (free tier) and the Atlas M2 and M5 (shared tiers) have operational limitations that you should be aware of. Most importantly:

Note that the maximum number of operations per second, the number of open connections, and the amount of data that can be transfered have been raised specifically for Atlas clusters migrating from mLab using the migration tool detailed in this guide. Please email support@mlab.com for more details.

We recommend reviewing all of the Atlas operational limitations:

If you are concerned about these limitations please email support@mlab.com with the deployment identifier for the mLab deployment you want to migrate so that we can provide advice. Again note that some limits have been raised specifically for Atlas clusters migrating from mLab.

Manually Creating the Target Atlas Cluster

The migration tool will enable you to automatically create the target Atlas cluster, but if you’d like to manually create it, here are the steps:

  1. Ensure that the correct target project (within the correct organization) is selected.
    • From the “Context” menu in the top-left corner select a specific project.
  2. Click on the “Build a Cluster” or “Build a New Cluster” button to create an Atlas cluster, noting our recommendations in the table below.
IMPORTANT:  
Cloud Provider & Region Select the same region as the source mLab deployment.
Cluster Tier Size the target Atlas cluster to be at least as performant as the source mLab deployment in order to make the migration process as smooth as possible. You’ll be able to seamlessly downgrade on Atlas within the Atlas Dedicated tiers (M10+) once the migration is complete.

Note that the Atlas Live Migration process is only available for the Atlas M10+ tiers.
Additional Settings > Version On the M10+ tiers select the same MongoDB release version as the source mLab deployment (3.4 or 3.6).
Additional Settings > Backup On the M10+ tiers select “Cloud Provider Snapshots” as the backup solution.
Cluster Name If you want to customize the name of your Atlas cluster, now is the time. This name will be part of the cluster’s connection string, and you will not be able to change it later.

Restrictions on Target Atlas Cluster Modifications

Once an Atlas cluster has been set as the target of a migration from mLab, you will not be able to:

These restrictions are in place to help ensure a smooth migration from mLab to Atlas. We recommend waiting 1-2 days or at least through a period of peak traffic before making these types of changes to the target Atlas cluster. This way if there’s an unexpected issue after migrating to Atlas, it will be much easier to determine the root cause.

You can lift the restriction on these types of cluster modifications if you cancel the migration. However once you’ve made these kinds of cluster modifications, the migration tool will no longer allow you to migrate to that cluster.

To cancel a migration:

  1. Log in to the target Atlas organization.
  2. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. From the left navigation select “mLab Account”.
  4. Locate the mLab deployment that you want to migrate to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Cancel Migration” to open the migration checklist for the given deployment.

Testing Connectivity

A critical step to ensuring a migration to Atlas with very minimal downtime is testing connectivity to the target Atlas cluster from all applications before cutting over from the source mLab deployment.

For each application that depends on this deployment:

  1. Log into a representative client machine.
  2. From that machine, download and install the mongo shell.
  3. From that machine, connect to your cluster using the exact connection string that has been published in Atlas’ UI.

This will ensure that each of your applications has network connectivity and working database credentials.

Importing from Source to Target

Live Migration process

The process used when migrating into the Atlas M10 and above

Atlas can perform a live migration of the source mLab deployment to the target Atlas cluster, keeping the target in sync with the source until you cut your applications over to the target Atlas cluster.

This seamless process is available for mLab Dedicated plan deployments as well as Shared plan deployments migrating to Atlas dedicated-tier clusters (M10 and above).

Do not cutover to the target Atlas cluster until you have tested connectivity from all applications (see “Testing Connectivity” section above) and ensured that all writes have stopped on the source mLab deployment.

You cannot use the renameCollection command during the initial phase of the Live Migration process. Note that executing an aggregation pipeline that includes the $out aggregation stage or a map-reduce that includes an out will use renameCollection under the hood.

Consider doing a trial run of this process by performing a partial migration that stops before the “Cut over” step. Once you are ready, start the Live Migration process again.

  1. Navigate to the “mLab Account” view.
    • From the “Context” menu in the top-left corner ensure that the target Atlas organization has been selected.
    • From the left navigation click “mLab Account”.
  2. Start the migration process.
    • Locate the mLab deployment that you want to start migrating to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Configure Migration” to start the migration wizard.
    • Follow the steps in the migration checklist to start the Live Migration process.
  3. Wait until the source and target deployments are in sync.
    • When Atlas detects that the source and target clusters are in sync, it starts an extendable 72-hour timer to begin the cutover procedure. If the 72-hour period passes, Atlas stops synchronizing with the source cluster. You can extend the time remaining by 24 hours by clicking the “Extend time” hyperlink any number of times.
  4. Prepare to cutover.
    • Click the “Prepare to Cutover” button to open a walk-through screen with instructions on how to proceed.
    • Copy and paste the connection string for your target Atlas cluster and prepare to change your connection string.
    • Do NOT proceed until you’ve tested connectivity from all applications (see “Testing Connectivity” section above).
  5. Cutover.
    • Stop writes to the source mLab deployment by stopping all application clients.
    • Wait for the optime gap to reach 0 (this should be extremely quick).
    • Click the “Cut over” button to stop the target Atlas cluster from syncing from the source mLab deployment.
    • Restart application clients with the target Atlas connection string.

mongodump/mongorestore

The process used when migrating into the Atlas M0, M2, or M5 tiers

To migrate a mLab Sandbox (free) database to the Atlas M10 tier, you’ll need to first migrate to the Atlas M0, M2, or M5 tier. From there you’ll be able to upgrade to the Atlas M10 or above without needing to change your connection string yet again (7-9 minutes of downtime).

  1. Navigate to the “mLab Account” view.
    • From the “Context” menu in the top-left corner ensure that the target Atlas organization has been selected.
    • From the left navigation click “mLab Account”.
  2. Start the migration process.
    • Locate the mLab deployment that you want to start migrating to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Configure Migration” to start the migration wizard.
    • Follow the steps in the migration checklist to start the import of your data and indexes.
  3. Perform a test migration.
    • The “Test Migration” step of the migration checklist will delete any data existing on the target Atlas cluster and then run a mongodump on your source mLab deployment followed by a mongorestore into the target Atlas cluster.
    • We strongly recommend performing a test run of the migration. The test run will not only give you an estimate for how long the process will take, but it will validate that the process will work for your particular set of data and indexes.
  4. Perform the real migration.
    • Do NOT proceed until you’ve tested connectivity from all applications (see “Testing Connectivity” section above).
    • Stop writes to the source mLab deployment by stopping all application clients.
    • Click “Begin Migration” which will perform the same actions as the test migration but it will also change the role of your database user(s) on your source mLab deployment to be read-only (as a safeguard for ensuring that writes have stopped).
    • Wait for the import to complete with success.
    • Restart application clients with the target Atlas connection string.

If an unexpected error occurs during the real migration, 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 ahead of time will help avoid the need to do this.

Importing from Source to Target: Live Migration Process FAQs

Q. When cutting over to Atlas during the Live Migration process, do I need to stop my application?

We strongly recommend that you perform the cutover step of the Live Migration process by stopping all writes to the source mLab deployment before clicking on the “Cut over” button and directing traffic to the target Atlas cluster. Only by executing the cutover using this strategy can we guarantee that the migration will neither lose data nor introduce data consistency issues.

However, if your application cannot withstand even a few minutes of downtime, you may be seeking a method by which you can cut over to Atlas without stopping your application.

A custom cutover strategy is possible, but you will be responsible for reasoning through all of the possible issues that could arise from that strategy. Such analysis is very specific to the way your application works, and MongoDB can make no guarantees about the correctness of the migration in these cases.

Important things to know about the Live Migration process for a Replica Set:

If you decide to allow your application to read and/or write to both the source and the target during the cutover phase you will be responsible for ensuring that your application can handle any consequence of this strategy. For example, your application may lose data, unintentionally duplicate data, generate inconsistent data, or behave in unexpected ways.

This FAQ is applicable only if the target Atlas cluster is a Replica Set. When migrating a Sharded Cluster the target cluster is not available on the network for 3-5 minutes after the cutover button is pressed and replication from the source to the destination has stopped.

Deleting the source mLab deployment

To stop incurring charges on mLab for a for-pay deployment, you must ensure that the mLab deployment has been deleted. We recommend deleting it as soon as you are confident that it has been successfully migrated to Atlas, and you no longer need it.

Note that mLab bills at the start of each month for all chargeable services provided in the prior month, so you will still be charged one additional time even after your mLab account stops incurring charges.









  1. Size of data plus indexes of mLab deployment. This is the value under the “SIZE” heading in mLab’s UI. 

  2. In addition to stopping replication, the “Cut over” button during a Live Migration process will also perform a rolling restart of the target Replica Set in order to re-enable a setting that is temporarily disabled during a Live Migration, ttlMonitorEnabled