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 have been 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:

Notifications about this deadline have been emailed to all mLab accounts. If you are unsure what your deadline is, log into your mLab account and read the banner at the top of the page.

Learn how to migrate.

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.

Learn how to migrate.

Q. How much technical expertise does the migration process require?

The migration process does require some amount of technical ability (basic software development skills/experience).

Specifically it requires the ability to change the database connection string that the application is using (via configuration files, environment variables, the source code itself, etc.) and the ability to deploy the change in a way that is coordinated with the overall migration process. Being able to code is not required for the migration to Atlas.

That said, the migration process is driven via a wizard-like web UI that was custom-built for this purpose. You can perform trial migrations easily with the tool to get a sense for the complexity of the task before using the tool to perform the actual migration.

If your team does not have the necessary technical expertise and is seeking the help of a contractor, please email support@mlab.com.

Q. How do I migrate to Atlas?

Create an Atlas organization, connect it to your mLab account, and then use the mLab->Atlas migration tool that was custom-built to make it easy to migrate mLab databases to Atlas with minimal downtime.

It’s very important that you use the mLab->Atlas migration tool to migrate instead of manually migrating since the migration tool will automatically configure your target Atlas cluster to give you the best experience on Atlas as a user coming from mLab. It will also give you access to a discount on Atlas support plans.

Please email support@mlab.com if for reason you feel like you can’t use this specialized tool.

Before Migrating:

How-To Migrate:

Use the appropriate guide to access and use the mLab->Atlas migration tool. The general guide can be used to migrate any mLab deployment to Atlas, but we recommend using the guide that is specifically targetted to your use case:

Free mLab accounts

For-pay mLab accounts

For general Atlas questions or migration-related questions/issues, please email support@mlab.com. We have a dedicated team ready to help!

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. Does Atlas have a Data API?

If you are using the mLab Data API note that 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 Heroku.

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. What if I am using the mLab Heroku add-on?

mLab will be shutting down its Heroku add-on on November 10, 2020.

You can either:

We have custom-built tools to make both of these options relatively easy.

Please see Shutdown of mLab’s Heroku Add-on on November 10, 2020 for details.

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 multiple free-tier mLab Sandbox databases to Atlas?

If you have multiple mLab Sandbox databases that you would like to migrate to Atlas, note that:

(1) There is a limit of one Atlas free-tier cluster (M0) per Atlas project.

However, you can have multiple Atlas M0 clusters across multiple projects.

(2) The Atlas M0 supports multiple databases.

It may make sense for you to migrate multiple mLab Sandbox databases into a single Atlas cluster. In this case, you can use the mLab->Atlas migration tool to migrate the first Sandbox database and then manually run mongodump/mongorestore (after stopping writes) to migrate additional Sandbox databases into the same target Atlas cluster.

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.

The more modern mongodb+srv:// connection string format is the recommended (and default) Atlas format because it 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 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).