Migrating to MongoDB Atlas

mLab is now part of MongoDB, Inc., the company behind the database that powers your application(s). For background please read our announcement on October 9, 2018.

As part of merging the two organizations we are working with users to migrate to MongoDB Atlas and sunsetting mLab’s service.

Migration Timing and Details

mLab and MongoDB Atlas have worked together to do the following:

Our goal is to have users migrate to MongoDB Atlas by the first half of 2020 but note that we are still in the process of sending out official notifications.

If your account has been sent a notification with an official deadline, you will see a banner with the deadline date after you’re logged into your mLab account. If not, rest assured that your database deployment(s) and all of our services will operate as usual, and you will be provided with plenty of advance notice to migrate.

If you would like to migrate now see the section below about migrating now.

FAQ

Q. Does Atlas have similar management tools/features that mLab has?

Feature-wise, the two MongoDB-as-a-Service products are more similar than they are different. Some capabilities that may be new to mLab users include cross-region replication; geographic data distribution via Global Clusters; enterprise security features such as encryption key management, granular database auditing, and LDAP support; and tight integration with the MongoDB Connector for Business Intelligence (BI) and MongoDB Charts.

mLab’s engineering team was integrated into the greater MongoDB engineering organization, and we have been working on new features together.

Note that some functionality is different on Atlas. For example, you will not be able to have mongodump-based backups automatically taken and uploaded to your own S3 bucket, but you will be able to achieve a similar end-goal using Atlas’ features.

Q. Will you migrate my mLab deployment for me?

We cannot perform the migration on your behalf, but we have built a migration tool that makes it very easy for you to migrate.

Importantly note that migration process will require you to change the connection string which your application is using to connect to your database.

Q. How much downtime is required?

If you are migrating into one of Atlas’ dedicated-tier Replica Set clusters (M10 or above), the only downtime that will be necessary is the time it takes for you to stop writes to the source mLab deployment and restart your application servers with a new connection string that points to the target Atlas cluster. The reason why this process is so seamless is that it uses a Live Migration process.

Migrating to one of Atlas’ shared-tier clusters (M0, M2, or M5) or an Atlas Sharded Cluster will require a bit more downtime.

Q. Will the source mLab deployment still be available once I start the migration?

The source mLab deployment will not be deleted by the migration wizard. Its data will remain intact until you manually delete the mLab deployment (from mLab’s UI) after you are confident that it has been successfully migrated to Atlas and that you are no longer using it.

If you are migrating into an Atlas shared-tier cluster (M0/M2/M5) please note that the “Migrate” step (but not the “Test Migration”) step will change the role of your database user(s) on your source mLab deployment to be read-only (view mongodump/mongorestore process).

If you are migrating into an Atlas dedicated-tier cluster (M10+), the migration process will not make any changes on the source mLab deployment whatsover (view Live Migration process).

Q. Can I migrate now to Atlas?

Yes - all of mLab’s users can migrate now.

Before migrating:

How to migrate now:

Migrating to Atlas requires a connection string change, but if you have a for-pay mLab deployment and your target Atlas cluster is running on the Atlas M10 or above, you’ll be able to perform the migration with very minimal downtime to your application.

Step-by-Step Guide to Migrating:

The guide will walk you through connecting your Atlas organization to your mLab account(s) and then give you access to the migration tool that was built specifically for making migrations from mLab to Atlas as easy as possible.

For migration questions or issues, see the support-related FAQ at the bottom of this page.

Q. Should I migrate to Atlas yet?

We recommend starting the process to migrate to Atlas if:

Q. Does Atlas have a Data API?

MongoDB Atlas does not have a data API. However, we have open-sourced the mLab Data API and made it easy for you to self-host the mLab Data API on AWS.

Once you have re-configured your application to use your self-hosted mLab Data API, you’ll be able to migrate your mLab-hosted deployments to MongoDB Atlas.

Q. Does Atlas have a Heroku add-on?

Not at this time. However, MongoDB plans to build an integration between MongoDB Atlas and Heroku. You will be able to continue to use mLab via its add-on at Heroku until the new integration is available.

Importantly note that many applications use Heroku with mLab without using Heroku’s add-on program. This means that unless your organization needs to be billed by Heroku instead of MongoDB, you should be able to migrate to MongoDB Atlas even before the MongoDB Atlas Heroku add-on is available.

If you go this route you just need to:

Q. Does Atlas support mongodump-based backups to custom S3 buckets?

Atlas’ backup service does not take mongodump-based backups. Instead, Atlas snapshots are generally in the form of MongoDB database files. Database files tend to be orders of magnitude faster to restore than mongodump-based backups, especially for larger deployments (since indexes don’t have to be re-built).

Also, although Atlas currently does not support archiving backups to custom S3 buckets it does have an API for programmatically accessing backups:

Endpoints for restoring or downloading an Atlas snapshot:

How to restore a downloaded Atlas snapshot:

Once you have downloaded an Atlas snapshot, you can also archive the backup to S3 using the AWS API either directly or via an AWS SDK in the language of your choice.

Q. How do I migrate my free mLab Sandbox to a for-pay Atlas cluster?

Since mLab is in the process of sunsetting its service, if you want to upgrade your existing mLab Sandbox database, you’ll need to migrate to one of the Atlas for-pay clusters:

Step-by-Step Guide to Migrating:

Email support@mlab.com if you have questions about Atlas or the migration process.

Q. Why is my Atlas connection string prefixed with “mongodb+srv://”?

MongoDB supports two connection string formats, the standard connection string format (prefixed with mongodb://) and the DNS seedlist connection string format (prefixed with mongodb+srv://). mLab only supports the standard connection string format while MongoDB Atlas supports both.

If your driver version is compatible with 3.6 or above, we highly recommend using the mongodb+srv:// connection string format as this more modern format will make it significantly less likely that you’ll need to change your connection string in the future (e.g., in the event of additional nodes in a Replica Set cluster or additional mongos routers in a Sharded Cluster).

If you would like to see how the DNS records have been configured, you can use nslookup. An example follows:

Example Atlas Cluster

DNS Seedlist Connection String Format

mongodb+srv://<username>:<password>@my-atlas-cluster-mdyjt.mongodb.net/test?retryWrites=true&w=majority

Standard Connection String Format

mongodb://<username>:<password>@my-atlas-cluster-shard-00-00-mdyjt.mongodb.net:27017,my-atlas-cluster-shard-00-01-mdyjt.mongodb.net:27017,my-atlas-cluster-shard-00-02-mdyjt.mongodb.net:27017/test?ssl=true&replicaSet=my-atlas-cluster-shard-0&authSource=admin&retryWrites=true&w=majority

How to Examine the DNS SRV Record

% nslookup -type=SRV _mongodb._tcp.my-atlas-cluster-mdyjt.mongodb.net
...

Non-authoritative answer:
_mongodb._tcp.my-atlas-cluster-mdyjt.mongodb.net    service = 0 0 27017 my-atlas-cluster-shard-00-02-mdyjt.mongodb.net.
_mongodb._tcp.my-atlas-cluster-mdyjt.mongodb.net    service = 0 0 27017 my-atlas-cluster-shard-00-00-mdyjt.mongodb.net.
_mongodb._tcp.my-atlas-cluster-mdyjt.mongodb.net    service = 0 0 27017 my-atlas-cluster-shard-00-01-mdyjt.mongodb.net.

% nslookup -type=TXT my-atlas-cluster-mdyjt.mongodb.net
...

Non-authoritative answer:
my-atlas-cluster-mdyjt.mongodb.net    text = "authSource=admin&replicaSet=my-atlas-cluster-shard-0"

As noted in the documentation for the DNS Seedlist Connection Format, use of the +srv connection string modifier automatically sets the tls (or the equivalent ssl) option to true for the connection.

If you would like to access the non-SRV (Standard Connection String Format) connection string for your Atlas cluster, you can open the “Connect” dialog window, select “Connect Your Application” option, and then choose the oldest version of any driver.

Some DNS servers do not fully support SRV records, so using the non-SRV connection string may be a better option for you.

Q. Why does my Atlas connection string include w=majority and retryWrites=true?

The w=majority option will ensure that all writes are durable to at least a majority of the nodes in the cluster (Atlas clusters come default with 3 electable nodes). This is recommended and will ensure data is not potentially rolled-back during recovery from the loss of a node. Without this setting it is possible for the cluster to lose writes in certain failure scenarios.

The retryWrites=true option will enable retryable writes which will provide your application with more resilience when replica set failovers occur.

These two options are optional but strongly recommended. If you leave them out during the migration process we highly recommend including them once you’ve successfully migrated to Atlas.

Q. How do I estimate how much I will spend on Atlas for similar services?

Our intent is that your all-in Atlas costs do not exceed what you’re paying at mLab. However it’s important to understand that Atlas plans are packaged differently than mLab’s in that clusters, backups, data transfer, and support are priced separately.

Cost Type Description Notes
Cluster Service cost which includes the VMs and disks  
Backup Service cost which depends on the size of the data set and the retention policy. Only applies to Atlas dedicated-tier clusters (M10+). Roughly 6% of Cluster costs
(assuming Cloud Provider Snapshots and 8 retained daily backups to match mLab’s default; varies based on workload).
Data transfer Service cost. Only applies to Atlas dedicated-tier clusters (M10+). Roughly 7% of Cluster costs
(assuming applications connecting from within the same cloud region; varies based on workload).
Add-on feature Service cost for optional features such as MongoDB Connector for BI.  
Support Subscription cost priced as a percentage of total service cost, with a minimum. Depends on the selected support plan1.

To see an estimate of how much a given mLab deployment will cost on Atlas (including backups and data transfer) start the steps to migrate a specific deployment.

If you are concerned that data transfer costs will be disproportionately high, ensuring that your application and database are running in the same cloud region will not only allow you to minimize data transfer costs but also will minimize network latency and network instability. You can also reduce network usage by adding &compressors=snappy,zlib to your connection string to enable compression between your application and the database; driver compression is not enabled by default but can be enabled as of MongoDB 3.6. For help please contact support@mlab.com.

If you have questions or concerns about pricing on Atlas please email support@mlab.com.

Q. Can I migrate to a different cloud region while migrating from mLab to Atlas?

We highly recommend running your application servers and your databases in the same cloud region. Otherwise you could have issues with network latency and instability.

The migration tool that was custom-built for migrating deployments from mLab to Atlas does not support cloud region changes. This is because migrating to Atlas while simultaneously changing regions will likely complicate the diagnosis of any unexpected issues that arise.

However, we document steps below to accomplish the same end-goal in a way that minimizes risk.

Migrating to an Atlas dedicated-tier (M10 or above) cluster in a different cloud region

Different cloud region but same provider (e.g., AWS us-east-1 to AWS us-west-2)

If you are migrating from a source mLab Dedicated plan or migrating to a target Atlas M10 cluster or above, you can perform the following steps in order to also change cloud regions (same cloud provider):

  1. Migrate to the same cloud region on Atlas using our migration tool.
  2. Wait a couple days or through a period of peak traffic to ensure that the migration to Atlas was successful.
  3. To minimize network latency ensure that your application is or will soon be connecting from the region to which you are migrating.
  4. Migrate your new Atlas cluster to the new region.
    • This operation is seamless and doesn’t require any change in connection string.

Alternatively, if you would prefer to migrate to the new cloud region before you migrate to Atlas please email mLab Support (support@mlab.com), as we will likely be able to help.

Different cloud provider (e.g., AWS us-east-1 to GCP us-east4)

If you are migrating from a source mLab Dedicated plan or migrating to a target Atlas M10 cluster or above, you can perform the following steps in order to also change cloud providers. Note that these steps will only be possible if mLab supports the cloud region that you want to migrate to and will not work for Azure Classic mLab deployments.

  1. To minimize network latency ensure that your application is or will soon be connecting from the region to which you are migrating.
  2. Open a ticket with mLab Support (support@mlab.com) for help migrating to a cloud region that’s part of a different cloud provider.
  3. Wait a couple days or through a period of peak traffic to ensure that the region change was successful.
  4. Migrate to the same cloud region on Atlas using our migration tool.

Migrating to an Atlas shared-tier (M2/M5) cluster in a different cloud region

If you want migrate to one of the cloud regions that mLab supports on its Shared plans:

  1. To minimize network latency ensure that your application is or will soon be connecting from the region to which you are migrating.
  2. Open a ticket with mLab Support (support@mlab.com) for help migrating to a different Shared plan cloud region
  3. Wait a couple days or through a period of peak traffic to ensure that the region change was successful.
  4. Migrate to the same cloud region on Atlas.

Still need help migrating to a different cloud region?

If none of options above work for your situation, email mLab Support (support@mlab.com). We may be able set an override which will allow you to use the migration tool to migrate to a different cloud region on Atlas.

Q. Can I migrate from a free mLab Sandbox to an Atlas M10?

The migration tool that was custom-built for migrating from mLab to Atlas unfortunately does not support migrations from the free mLab Sandbox plan to an Atlas dedicated-tier cluster (M10 and above). However, it’s possible to perform a migration of this type manually.

Option 1 (requires downtime but does not require you to install and manually run mongodump/mongorestore)

  1. On mLab use the “Create new” button to create a brand-new Dedicated M1 Standard plan deployment in the same cloud region running MongoDB 3.6.x.
  2. Stop writes to the source mLab deployment.
  3. Take a one-time mongodump of the source mLab deployment from the “Backups” tab.
  4. Restore the backup into the newly-created Dedicated M1 Standard plan deployment using the “Restore from backup” button.
  5. Use the migration tool to migrate this new deployment to MongoDB Atlas.

Option 2 (minimizes downtime but requires you to install and manually run mongodump/mongorestore)

  1. Create the target Atlas M10 cluster running in the same cloud region on MongoDB 3.6.x.
  2. Stop writes to the source mLab deployment.
  3. mongodump the source mLab deployment.
  4. mongorestore to the target Atlas deployment.

Email mLab Support (support@mlab.com) if you have questions or need assistance with one of the options above.

Q. Can I downgrade while migrating from mLab to Atlas?

The migration tool that was custom-built for migrating from mLab to Atlas does not support downgrades. Instead we recommend performing the following steps instead.

To downgrade RAM or downgrade from a dedicated-tier deployment to a shared-tier deployment:

  1. Downgrade your mLab deployment.
    • Note that downgrading from an mLab Dedicated plan to a mLab Shared plan as well as downgrading to an mLab Sandbox database requires downtime and a connection string change. However, it does not require you to install and run mongodump/mongorestore manually.
  2. Wait 1-2 days or through a period of peak traffic to ensure that the downgrade was successful.
  3. Use the migration tool to migrate to the most equivalent Atlas cluster (the tool will guide you through this).

To downgrade the disk size on a dedicated-tier deployment:

In general the performance of dedicated-tier (M10 or above) Atlas clusters are tied to disk size - the smaller the disk size, the lower the throughput.

  1. Use the migration tool to migrate to the most equivalent dedicated-tier Atlas cluster (the tool will guide you through this).
  2. Wait 1-2 days or at least through a period of peak traffic to ensure that the migration to Atlas was successful.
  3. Reduce the storage size on the new Atlas cluster.
    • This operation is seamless and doesn’t require any change in connection string.

Q. How do I get help? Who do I direct questions do?

For migration-related questions or issues, email mLab Support (support@mlab.com). mLab Support will be your main point of contact until you have successfully migrated to Atlas and will work closely with Atlas Support and Atlas Engineers as needed.

To expedite the process include your mLab account name or mLab deployment identifier as well as a link to your Atlas cluster, project, or organization.







  1. Our intent is that your all-in Atlas costs do not exceed what you’re paying at mLab. As such in some cases we will be able to offer discounts on Atlas support plans (email support@mlab.com for help).