MongoDB Migration Tool - Automated

Overview

The following is an overview of the ObjectRocket Automated MongoDB Migration Tool to help you migrate your existing Heroku Compose MongoDB instance over to ObjectRocket’s DBaaS platform. It was built to automate much of the process, giving customers the ability to migrate without any downtime on their application.

We are leveraging native capabilities that exist in MongoDB to make a copy of your existing data and write it to a point-in-time in the new ObjectRocket MongoDB instance. Your application can even continue to write to and read from the Compose MongoDB instance while this migration is taking place. All of the writes that occur during the migration will be captured on the new ObjectRocket MongoDB instance, before the migration is declared complete. There should be no downtime on the part of your application. The migration tool’s user interface (UI) will take you through the steps necessary to complete the migration.

Note

Read through this entire documentation before you get started.

Warning

This migration tool can only be leveraged for migrations involving MongoDB version 3.0 and later. Any migration for MongoDB versions prior to 3.0 should leverage the MongoDB Migration - Manual approach. 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 Information on Heroku Application

You will need to verify the Heroku application name when using the migration tool.

  1. Login to the Heroku Control Panel
  2. Verify the name of the application that has the Compose MongoDB instance.
  3. Note this information and keep it in a place that you can access during the migration.

Gather Information on Compose MongoDB Instances

You will need to capture some basic pieces of information about your existing Heroku Compose MongoDB instance. The migration tool will ask you for the Compose URI, Compose MongoDB version, and Compose MongoDB size. You will be able to view this information in the Compose control panel.

  1. In the Compose control panel, navigate to the Admin section and then click the Overview tab. There you will see the URI, version, and current size of MongoDB that you are running.
  2. Note this information and keep it in a place that you can access during the migration.
Compose control panel with MongoDB details.

Create new User with oplogAccess on Compose MongoDB Instance

To capture writes that occur during the migration, you will need to setup a new user with oplogAccess permissions. If you already have a user with this permission, you can skip this step. You cannot add this permission to an existing user - you have to create a new user with this permission. You can do this all in the Compose control panel.

  1. To create a new user with ”oplogAccess“, open the Compose control panel, navigate to the Admin section, and then click the Users tab. On the User’s tab, click Add User.
Compose control panel with Add user details.
  1. On the Compose control panel, enter a username and password, select the oplogAccess permission, and then click Add user. The migration tool won’t ask you for this information; it will be leveraged during the migration flow.

Migrate the Instance

Follow these steps to begin the migration process

  1. To start the ObjectRocket MongoDB migration tool, use your browser to navigate to the ObjectRocket MongoDB Migration Tool.
ObjectRocket MongoDB migration tool welcome page
  1. Sign in to the Heroku account that contains the application(s) with a Compose MongoDB add-on that you need to migrate over to ObjectRocket MongoDB.
Heroku sign-in page.
  1. When prompted, authorize ObjectRocket on Heroku account.

This screen will ask you to authorize ObjectRocket to have read and write access to your apps, resources, excluding account information. This is necessary for us to access the Compose MongoDB add-on on the app and provision a new ObjectRocket MongoDB add-on. Both of these will be necessary for a successful migration.

Warning

Without this authorization, the ObjectRocket MongoDB Migration Tool cannot be leveraged for your migration. Once the migration is complete and finalized by you, this access will be removed.

Heroku authorization page.
  1. Enter the Compose information that you captured prior to starting the ObjectRocket MongoDB migration tool (the Compose MongoDB URI, version, and instance size). You will also be prompted for the storage engine of the Compose MongoDB instance (mmap or WiredTiger). If you don’t know the storage engine, we can auto-select it for you based upon the version of MongoDB provided.
Compose information input page.
  1. Confirm the appropriate MongoDB size from the drop-down list box and then click Create ObjectRocket MongoDB Instance

Based upon what you provided for the Compose inputs, the migration tool populates the drop-down with recommendations for the ObjectRocket MongoDB instance size to provision.

Once you confirm the selection, a new instance will be created in your Heroku account. The current pricing will be listed on this page as well.

Note

In order for a MongoDB migration to be successful, the target instance needs to be the same MongoDB version as the source Compose MongoDB instance and large enough to accommodate the data. The dropdown will be preselected with the suggested ObjectRocket MongoDB instance size and we are configuring the appropriate version based upon the Compose MongoDB instance provided in the previous step. In the event that the provisioning of the ObjectRocket MongoDB Instance fails, please reach out to our Support Team for assistance.

Warning

We are aware of an issue which can occur in cases where the Migration Tool has provisioned an instance, but the migration itself has not yet started. We are working on a fix for this issue and expect to have a resolution shortly. In the meantime, if the migration is interrupted after provisioning the instance, but before starting the migration, manually remove the provisioned ObjectRocket Add-on from your heroku app and start over in the migration tool.

ObjectRocket MongoDB Provision and Pricing Page.

Everything is now ready to go to start the migration.

  1. Click Start Migration to begin the migration.

This starts the process of copying the existing data from the Compose MongoDB instance over to the new ObjectRocket MongoDB instance, and the migration tool keeps track of new writes that occur on the source MongoDB database while the migration is taking place.

Finalize Migration

Your ObjectRocket MongoDB instance is now ready to go. All of the data from the Compose MongoDB instance has been copied over and any writes that occurred on the Compose MongoDB instance during the migration have also been written to the new ObjectRocket MongoDB instance. We will continue to tail these writes for up to 24 hours from the starting time of the migration (when you pressed Start Migration on the previous screen).

Note

Before you click Finalize Migration, you need to change the connection strings in your application and any other processes that were accessing your Compose MongoDB instance. Once you click Finalize Migration, we will disable the tailing of the writes that are occurring on the Compose MongoDB instance.

  • To finalize the migration, click Finalize Migration.
ObjectRocket Finalize MongoDB Migration page.

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.

An optional step is to take a recent backup and download the backup file via the Compose Control Panel before you destroy your Compose MongoDB instance.

  • To delete the Compose MongoDB instance run the following command from the CLI:
$ heroku addons:destroy compose