MongoDB Migration - Manual¶
The following is a step by step flow to help you migrate your existing Heroku Compose MongoDB instance over to ObjectRocket leveraging the mongodump and mongorestore utilities available in MongoDB. If at any time you have any questions or need help, just contact our Support Team.
Before You Get Started¶
Before you get started with the ObjectRocket MongoDB Migration Tool, you will need to do a few things in the Compose control panel.
Gather Info on Compose MongoDB Instance¶
Confirm the current version and size of your existing Compose instance by accessing your Heroku Compose add-on in the control panel.
Navigate to the
Admin section and the
Overview tab and you will see the current size and version of MongoDB that you are currently running.
Provision ObjectRocket MongoDB Instance and Setup¶
Provision the corresponding Heroku ObjectRocket MongoDB instance by running the following CLI command:
Version 2.6 Example
$ heroku addons:create ormongo:5-mmap --version 2.6
Version 3.0 Example
$ heroku addons:create ormongo:5-mmap --version 3.0
You will need to specify the appropriate size and version flag needed in the command based upon the results in Step 1. For example, if your current version is 3.0, you would need to specify that flag in the command line for Step 2. It is very important that the appropriate version is selected in order for the migration to be successful. Also, ensure that you are selecting a size from the ObjectRocket offering that can accommodate your current MongoDB instance size.
NOTE! Heroku will automatically select the appropriate region for the ObjectRocket MongoDB instance based upon the region where your Heroku app resides.
ObjectRocket MongoDB Plan Sizes
|ObjectRocket Plan||Plan API Value||Price|
NOTE! If you need a larger size, just contact our Support Team.
ObjectRocket MongoDB Version Flag Options
Once you have successfully created your ObjectRocket MongoDB instance, you will need to get it configured correctly and ready for migration.
Any users that exist on the Compose MongoDB instance will need to be added to the new ObjectRocket MongoDB instance. As a reminder, you will need to add users via the ObjectRocket control panel.
Open the ObjectRocket Control Panel with the following CLI command:
$ heroku addons:open ormongo
The ObjectRocket Control Panel will open to the Instance Details page.
Add Database button
Name your database and provide a Username and Password. Click the
Add Database button
NOTE! In order to complete the migration, it is only necessary to set up an initial user for the database that is on the existing Compose MongoDB instance. Additional application users for the database can be added after database creation.
As a reminder, it is also necessary to locally replicate the config variables so your development environment can operate against the ObjectRocket MongoDB instance.
Migrate the Instance¶
Follow these steps to begin the migration process
- Stop your application
You will need to temporarily stop your application and any process that is writing to your Compose MongoDB instance. Once you are finished with the migration, you will need to restart your application.
- Run a mongodump
The next step will be to get a copy of the data that you have on your existing Compose MongoDB instance. You will be leveraging the mongodump utility that is available as part of MongoDB. Read through the documentation to review any potential impacts to your MongoDB instance during the mongodump process.
We recommend that you leverage a MongoDB package version that corresponds with the version of MongoDB that you are running. For example, if your Compose MongoDB instance is version 3.0, make sure that the package you use to run mongodump is MongoDB 3.0.
Perform a mongodump on your existing Heroku Compose MongoDB instance by running a command similar to the following from the system command line. Your values will differ.
mongodump --host candidate.61.mongolayer.com:12345 --authenticationDatabase app123456789 -u username -p password -d app123456789 --out /path/migration/dump
This will create a database backup in the directory specified.
- Run a mongorestore
This step will involve writing the data that you just created with mongodump to your new ObjectRocket MongoDB instance. For this step you will be leveraging the mongorestore utility that is part of MongoDB. Read through the documentation to review any potential impacts to your MongoDB instance during the mongorestore process.
We recommend that you leverage a MongoDB package version that corresponds with the version of MongoDB that you are running. For example, if your ObjectRocket MongoDB instance is version 3.0, make sure that the package you use to run mongorestore is MongoDB 3.0.
Perform a mongorestore of the resulting mongodump on your new ObjectRocket MongoDB instance by running a command similar to the following from the system command line. Your values will differ.
mongorestore --host "d0b2233b28111afc85cce7d5d28c8103/iad2-c7-2.mongo.objectrocket.com:45678,iad2-c7-1.mongo.objectrocket.com:45678,iad2-c7-0.mongo.objectrocket.com:45678" --authenticationDatabase app123456789 -u username -p password /path/migration/dump
Note! To reduce application downtime to as low as possible, you have the option to tail the oplog as part of the migration. By recording the most recent oplog operation before starting the mongodump and mongorestore, you can then apply operations from that point forward until you are ready to cut-over your application. Tailing the oplog reduces downtime by keeping the destination nearly in sync with the source until the application is stopped for the final cut-over. It’s recommended you refer to MongoDB Tailable Cursors documentation and your language’s libraries that support this type of process.
We expect that this extra option will rarely be needed and that most migration downtimes will be minimal. This step would only be needed for larger MongoDB migrations with very limited tolerance for any downtime. If you feel that you need this optional step and need help, feel free to contact our Support Team <mailto:email@example.com>.
- Change Connection Strings
Replace the old Compose MongoDB instance connection string in your application to the new ObjectRocket MongoDB instance connection string. If you had any other processes connected to the Compose MongoDB instance, you will need to change those connection strings over as well.
- Restart your application
Restart your application and any other processes that you stopped previously.
- Destroy Compose MongoDB instance
Verify that your application is working as expected with the new ObjectRocket MongoDB instance. Once this is done, get rid of your Compose MongoDB instance. You can do this with the following command from the CLI:
$ heroku addons:destroy compose
Note! You might want to take a recent backup and download the backup file via the Compose Control Panel before you destroy your Compose MongoDB instance.