MongoDB Migration - Manual

Overview

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.

Compose control panel with MongoDB details.

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

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
2GB mmap 2-mmap $46
5GB mmap 5-mmap $95
10GB mmap 10-mmap $163
20GB mmap 20-mmap $278
50GB mmap 50-mmap $646
100GB mmap 100-mmap $1,290

Note

NOTE! If you need a larger size, just contact our Support Team.

ObjectRocket MongoDB Version Flag Options

  • 3.0
  • 2.6

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.

Select the DATABASES tab

OR instance details page.

Click the Add Database button

OR database tab view.

Name your database and provide a Username and Password. Click the Add Database button

OR database create view.

Note

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

  1. 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.

  1. 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.

  1. 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

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:support@objectrocket.com>.

  1. 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.

  1. Restart your application

Restart your application and any other processes that you stopped previously.

  1. 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

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.