I was one of mLab’s happy customers until one fine day I got an email announcing that they’d been acquired by the more established mongoDB. Good for them (and us) I thought, until I read further down that all customers would have to migrate within the next year.
Ugh, great…
Databases has never been my forté. The less I deal with them the better. All that I know is from Googling & figuring out my problems along the way. So I avoided it as long as I could. But my website thiscodeworks.com which was hosted on mLab started growing and the more time that passed the uneasier I got.
Eventually I got down to it and it took me roughly 2 hours to set up and migrate the entire database — for anybody else it should take 30–45 minutes, maybe less. The process was pretty smooth and I only had a few hiccups which I was able to resolve after some trial and error and more Googling. For guidance, I followed mLab’s official instructions.
So like any programmer in today’s day and age, I feel like a complete scholar after the amount of time I’ve pored over the documentation, Stackoverflow and understanding all those errors. And thus, thought to generously share some guidance for anybody else stuck in the process.
Set up an Atlas account
- Register: Go to https://mongodb.com/cloud/atlas and register for an account. You can set it up for a company or as an individual. Take your time through the steps and choose the options that make sense for you.
- New project: After creating an account, navigate to https://cloud.mongodb.com/. In the upper left corner, under CONTEXT click on the dropdown menu and select +New Project. Name the project where you’ll be shifting the database to and add members if need be (you can add members later so it’s OK if you skip for now). You’ll be redirected to a screen where you can configure the project. Don’t do anything else.
- Link to mLab: Section B of mLab’s instructions are pretty self-explanatory. Under CONTEXT in the upper left corner, click on your organization name in the dropdown. From there go to “Settings” in the left navigation pane, then on the “General Settings” tab and click on the “Connect to mLab” button. You’ll be redirected to mLab where you will be asked to log in and authorize MongoDB Atlas. Once authorization is complete, you’ll be redirected back to MongoDB and you’ll see an option “mLab account” in the left pane for organization settings.
On a side note, here’s some information on what organizations and projects are if you’re a bit confused. The general hierarchy is Organizations > Projects > Clusters > Collections (this is where you see your data). You can view and access any level of the hierarchy in the CONTEXT dropdown menu in the upper left.
Start the migration
Under the CONTEXT dropdown menu, click on your organization, and then in the left navigation pane click on mLab Account. You’ll see a list of databases from your mLab account. On the right hand side of each, there will be a button with three dots. Click on that and select Configure Migration.
This brings you to the Atlas migration tool. You’ll see a checklist of activities that will guide you through the process. I went ahead and put my web app in maintenance mode to account for any downtime in the migration — I didn’t really have any downtime as I tested and did the transfer in development before pushing the changes to the live site, but just to be safe I put the site offline.
Configure migration
The first step requires you to select the project you want to migrate to. Choose the one we set up earlier. It should be empty because migration might delete any data within it.
Confirm the next two steps. They can be modified in the project settings as well later or on the side. If your project’s data is something that needs to be viewed by the public, then I’d suggest opening your project settings in another tab. Under the CONTEXT dropdown, select your project. Then in the left pane, click on Network Access.
You’ll see a green button on the right side of the screen that says +ADD IP ADDRESS. Clicking on that makes the following pop-up appear. If you want data to be publicly available, then click on the “Allow Access from Anywhere” button. Else if you want to keep it private for your eyes only, then click on “Add Current IP Address” to allow only devices from your current network to view data in the database. Confirm changes.
The 4th step is selecting your target cluster. Atlas will give you a list of settings that most closely match your current set up. You can modify the name, region and tier. Do your research and choose the cluster tier that best fits your needs & budget.
The tool will require you to enter billing info even if you’re migrating a free sandbox database. I didn’t get charged in the migration, but I did read online that some users with large database were charged ~$20–50.
Tip: If you’ve signed up for YC’s Startup School, you can use their promo code to get $500 in credits for a year!
Migrate deployment
Moving down the checklist in the migration tool, you’ll be asked to test connectivity. That’s done by taking the URI they provide you with and running it in Terminal with a mongo command.
You’ll first need to download & install the MongoDB shell. On MacOS, it was pretty straightforward installing with Homebrew. All I needed to enter in terminal was:
brew tap mongodb/brewAfter that I ran mongo followed by the URI provided, replacing the angled brackets with the correct information. <username> and <password> should be replaced with the login credentials of the database user of the project in Atlas. Replace <database> with the name of the project or “test”.
If you don’t know what to enter in user credentials, take a look at your database users by clicking on “Database Access” in the left navigation pane of a project. If you don’t see any user here, create one by clicking on the green button at the top right that says +ADD NEW USER.
For example, the URI for
- a project named pilot,
- username test-user, and
- password password123
will look like:
mongodb+srv://test-user:password123@server.example.com/pilot?retryWrites=trueEntering the following in terminal & getting the MongoDB server version number let me know whether or not the migration was successful.
mongo mongodb+srv://test-user:password123@server.example.com/pilot?retryWrites=trueOnce you’ve confirmed connectivity, run a test run and let Mongo do the rest of the work by clicking on the “Review Process & Begin” button next to migrate in the list.
Once the migration is complete, you’ll be provided with a MongoDB connection URI to insert into your application. Replace mLab’s URI and test the application locally. It should be up and running.
Post deployment
The last step on the checklist is deleting your mLab deployment. Once you’re satisfied that the migration process has worked well and you’re comfortable with the costs and ease-of-use, go ahead and delete it. Or if it’s free, then leave it as long as you want.
I sure hope this guide helped. If you’re interested in seeing all the data I transferred check out thiscodeworks.com — a crowdsourced repository of code snippets.
Happy coding!
