↑ Some pictures are missing in this blog post, to see all of the pictures press this link ↑
I used the following three references to build this guide. If you are comfortable with technical data, you may want to just use these or this Google Video Guide provided by mLab/MongoDB.
It is highly recommended that you find your Page 3 from the Cookbook that contains your email addresses, user ids, and passwords and add additional info from this upgrade so they are all in one place!
Otherwise, go to Page 6 for
Start: Simplified Guide to Update!!
- Nightscout on Heroku – Step-by-Step
Guide for Database Migration from
Discontinued mLab MongoDB to MongoDB Atlas
July 11, 2020, U. Rueth
You should consider migrating your existing mLab MongoDB, which currently stores your Nightscout data, to MongoDB Atlas before November 2020. There are other databases that also do the job, however, this document focuses on MongoDB Atlas migration only.
All these only concerns you if you have Nightscout running on Heroku – if you have it running on Azure, this doesn’t affect you!
All I’ll be writing here is based on the migration guide provided by mLab:
I just simplify it a little to make it easier – the truth is with the above migration guide J
Step 1 – Log in to Heroku and create an Atlas account
- Log into your Heroku account, as you’ll be working with it later.
- In the same browser, open a new tab and create an Atlas account here:
Step 2 – Connect your new Atlas account to your existing mLab (Heroku) account
and then on the green “Connect to mLab” button. Select your mLab (Heroku) account.
Step 3 – Prepare migration
- Click on the green leaf beside your organization in the top left corner of the Atlas page. This brings you to your organization’s Home view.
- From the left navigation select “mLab Account”.
- 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.
Step 4 – Run through the migration wizard
Please see part D of the migration guide – every step is well described there. For most steps, the right settings are already pre-selected. Just a few comments here:
- Step 2 – Import database user(s): This copies your mLab database user to your new Atlas database, i.e. you will require the same credentials (username & password) for the new database as for the old one.
- Step 6 – Test the migration: This will take some time, so be patient and wait until the process has finished. This gives you a good feeling of how long the real migration will take later.
- Step 7 – Test connectivity: This is a bit cumbersome for people not familiar with console/terminal commands. So you may either risk to skip this step or dig into the provided documentation – I will not help you with this.
- Step 8 – Ensure independence from the Heroku add-on’s config var: This is a very important step! Therefore step-by-step:
In your browser, switch back to the tab where you have logged into your Heroku dashboard and select your Nightscout project. o, Go to the Settings page: o Spot the variable with the name ““MONGODB_URI” or “MONGOLAB_URI” or “MONGOLAB_< colour>_URI” so similar. This variable has been automatically provisioned back when you deployed Nightscout on Heroku.
Copy the value of that variable, the old database connection string, which should look similar to this: MongoDB://<username>:<password>@…
Remember: The part before the colon is your old and new database username, the part after the colon up to the @ your database password. o Create a completely new variable at the end of your variable list with the variable name “MONGO_CONNECTION” and paste the old database connection string as value. You’ll need to modify that value as very last step later, however, it’s important to store its value for the time being, as the old variable will be automatically deleted.
- Step 9 – Migrate: Go for it! And be patient, it might take a while.
As of last and very important step: After migrating, you will be presented the new database connection string, which should look similar to this:
Replace the value of the MONGO_CONNECTION variable from step 8 above with this new database connection string and make sure that you use your old <username> and <password>.
All set! Nightscout should be working now. You may now manually delete the old mLab database from your Heroku project:
Start of: Simplified Guide to Update!!
Step 1 – Log into your Heroku account on a PC/Mac/Tablet – It is important to not switch devices during upgrade!
Pick here: https://heroku.com
Step 2 – Pick your Heroku site ID (⬢ <your user name>)
A – Go to the Settings (top middle of the page)
B – Pick Reveal Config Vars
C – Config Vars in alphabetical order – find the variable with the name MONGODB_URI or MONGO_CONNECTION or MONGOLAB_URI or similar. This variable was automatically created back when you originally deployed Nightscout on Heroku.
Copy the value of that variable, the old (current) database connection string, which should look similar to this: MongoDB://<username>:<password>@.
D – Scroll to the bottom of Config Vars and find the KEY and VALUE
Enter in the KEY box MONGO_TEMP and paste the copied text into VALUE then pick the Add button!
E – Now select the Overview and then pick the mLab MongoDB icon (Shown below)
***** Important to leave Heroku and mLab pages open and return to Step 3 below!
Step 3 – Now we will create an Atlas account
Pick here: https://www.mongodb.com/cloud/atlas
Note: If you do not see “Start free” then go to top right and log out and then go back and start Step 3 again!!!
Step 4 – Enter new account info – caution, it may require a new/not used yet email address.
Optional: How are you using MongoDB? = I’m migrating an app to Atlas (Cloud)
If necessary pick “Get Started” or “Skip” or “Dismiss” on bottom of the next page also!
Step 5 – Create a new Organization
If an Organization already existing then proceed to Step 8 otherwise continue!
Step 6 – Enter your Organization’s name (whatever you like!)
Step 7 – Finalize Organization here
Step 8 – Go to the Settings page
If you see the word “Clusters” then pick the “Organization Name” which is directly above the word “Clusters!
Step 9 – Select Connect to mLab – toward the bottom of page
Note: if you have trouble here with connecting to mLab then try switching to a different browser. IE Internet Explorer and starting again!
Step 10 – Authorize MongoDB Atlas here
Step 11 – Under Actions “…” and pick Configure Migration
Step 12 – Complete the tasks in the migration wizard
A: Target Project
B: Database Users
C: IP Whitelist – select Import Whitelist Entries
D: Target Cluster – Create or Select Target Cluster
Note: Create the most equivalent new cluster!!!
Migration is complete!! Note – you will see some warnings “!” which are not relevant to our Nightscout applications. Don’t worry!!
Step 13 – Complete the tasks in Migrate Deployment
A: Confirm Source and Target
B: Test Migration – Select Perform a Test Run
Note: Don’t forget to wait for the test to end!
C: Test Connectivity – Select Confirm Connectivity
Note: Pick the Copy icon in this display to capture your new connection string for your Heroku site to connect to the Atlas database.
D: Ensure Heroku Config Var Independence – Select
Note: We did step 1 shown here when we were in the Heroku site earlier!
E: Start Migration
**VERY Most IMPORTANT Step**
Stop the Heroku application — go back to your Heroku site and under Settings scroll down until you see the Maintenance switch! The sliding switch turns off the application!!
F: Start using Atlas – Cleanup is optional!
Step 14 – Almost done! Open your Heroku site again!
A – Pick your username and then
Go to the Settings (top middle of the page)
B – Pick Reveal Config Vars
C – Config Vars in alphabetical order – Look for a variable named MONGO_CONNECTION Please note: NOT MONGO_COLLECTION
If there is none then
D – Scroll to the bottom of Config Vars and find the KEY and VALUE
Enter in the KEY box MONGO_CONNECTION and paste the copied connection string into VALUE then pick the Add button!
E – Edit string by picking the pen icon
With your “username: password” found in the MONGO_TEMP string.
Note: Change just the part that is between:// and @ symbol ie.
username: password which is your old username and password with a “:” between them!
These are will NOT be the same as what you used to log into mLab!
Note: Check that your username is also after the “.net/” and before the “?” near the end of the string!
If you should lose your MONGO_CONNECTION, username, or password go to this document to retrieve them from mLab/MongoDB and then return here!
F – Restart site by turning the Maintenance mode back to OFF!
This STARTS/ENABLES your Heroku app again!
G – We restart the Heroku site by (upper right corner):
All done! If all has gone well, you have successfully migrated your mLab database to the new Atas database. I offer no guarantees other than I wrote this to the very best of my capabilities and hope you find it useful. If it doesn’t work then I offer to double your money back!! Oh, I almost forgot that it is free!
For additional help, you can contact me by FB Private Messenger @ Terry L. Witt
Addendum: Optional for the “OCD” users like me!!!
Heroku site page:
Delete mLab MongoDB
Note 1: If the Nightscout site is working with the new MONGO_CONNECTION string. MONGODB_URI is removed, then the migration was successful as that is the only bridge to your new ATLAS database.
Note 2: If you get API Secret or Application Error there most probably is an error in your MONGO_CONNECTION string and you will need to repair it!!