Migrating your database from Compose for MongoDB to IBM Cloud Databases just got easier—in fact, you can do it with just with the click of a button.
If you're thinking about making the switch to IBM Cloud Databases for MongoDB, our new migrations feature will allow you to easily move your Compose for MongoDB databases onto the new IBM Cloud Databases platform without having to manually backup and restore your data into another database from the command line using
The new migration feature is designed so that you can easily import your data over to IBM Cloud Databases for MongoDB by either importing all the data all at once from Compose or by tailing your Compose databases. If you're expecting a lot of writes to your Compose databases while migrating, then tailing is the option you're looking for until you're ready to make the complete shift to IBM Cloud Databases.
In this article, we'll walk you through the import process by migrating a database from Compose for MongoDB over to IBM Cloud Databases. Let's get started.
Creating the databases for MongoDB deployment
First off, in order to migrate, you'll need an IBM Cloud Databases for MongoDB deployment. You can provision one by going to the IBM Cloud Catalog and selecting Databases for MongoDB:
From here, you'll be taken to the provisioning page where you have a variety of options for your new Databases for MongoDB deployment. We're using the preferred version on IBM Cloud, which at the time of writing is MongoDB version 4.2.
Make sure that you've scaled your disk and memory for your Databases for MongoDB deployment to at least the same as your Compose for MongoDB deployment during this set up phase before provisioning. Otherwise, your new deployment will not have enough space to handle your data once the migration starts.
After you've made all your selections, and click the Create button to provision the database:
After the provisioning has finished, you'll be able to access your new database. Remember to change the administrator password of the new database by selecting the Settings tab and creating a new password:
After you change the password, go back to the Overview panel of your database. There, you will find the database credentials that you will use when setting up the migration from your Compose deployment over to Databases for MongoDB:
The change between Compose for MongoDB and Databases for MongoDB is that they are completely different architectures, so you have a couple of things to look out for:
- First, you want to make sure to provision enough memory and disk to support your new database. Basically, this depends on your use case. However, you will want to read up on disk, memory, and I/O in our documentation to determine the appropriate amount for your needs.
- Second, to make Databases for MongoDB more like the Compose experiences, we've recently introduced an autoscaling feature that will allow you to set autoscaling limits to disk and memory depending on your needs. So, once you reach a certain limit, Databases for MongoDB will automatically scale your deployment to whatever you set as an appropriate limit.
- Finally, make sure your application supports TLS certificates. You will need the certificate to successfully connect to your database.
And that's all for setting up your Databases for MongoDB deployment.
Starting the migration
When you're ready to start the migration process, head over to your Compose for MongoDB deployment. There, you will see the new Migrations tab at the top of the IBM Cloud console. Click the tab and it will take you to the Migrations panel:
From here, click on the Create Migration button, which will open up a panel where it provides you with some instructions on how migrations work and allows you to enter the Compose for MongoDB database you want to migrate from and the destination URI for your Databases for MongoDB deployment. An important point about migrating databases is that you cannot migrate all the databases within a single MongoDB deployment at one time; they will need to be migrated database-by-database, which is why you must include a source database to successfully start the migration process:
In this example, we'll walk you through migrating a database called
airlines within our Compose for MongoDB deployment.
Once you're in the Migrations panel, you will see two text boxes: Source Database Name and Destination URI. Where it says Source Database Name, you will need to enter the database within your Compose for MongoDB deployment that you want to migrate. In this case, we'll use the name
airlines. Where it says Destination URI, you'll insert your your Databases for MongoDB connection string along with a database name that will be created in your new deployment for the data. Your connection string will look something like this:
When entering the entire URI into the text box, make sure that you 1) substitute
$USERNAME with the database username, 2)
$PASSWORD with the database password associated with the user, and 3) change in the URI
ibmclouddb with the database name that you want your Compose data migrated into.
Since the source database is called
airlines, then we could also write
airlines as the database in the connection string. The database will automatically be created for you once the migration process begins. Finally, you have the option to Enable Tailing, which we'll look at more in the next section. For now, leave that unchecked.
With all the information filled out, it will look something like this:
Now, click Create. This will start the migration. You will be transferred to the previous page and shown the status of your migration. If everything is successful, you'll see something like the following:
One thing to keep in mind is that after migrating to your new Databases for MongoDB deployment, you will need to recreate all your previous users that existed in your previous Compose for MongoDB databases. Compose for MongoDB does not carry over your MongoDB users to the new deployment. Therefore, make sure that you've recreated those.
So, we've talked about how to do a simple migration, but what about migrations for critical applications that continuously write data to the database? For that, the answer is tailing. Let's see what that is, and how to migrate in that situation.
Tailing or syncing your database over time
Migrating might seem like a daunting task, especially if you have a critical application that's always writing to the database. In this case, you want the least downtime possible. With tailing, we have you covered here too.
Tailing means reading new data as it comes into MongoDB through the oplog. What this does is, after the initial bulk import of your MongoDB data on Compose to your new Databases for MongoDB deployment, the new database will continue to read the oplog of your Compose database for up to three days (or until you cancel the process). That way, when you're ready to completely cut over to the new database, all you'd need to do is switch out the connection strings from your Compose database to IBM Cloud Databases.
To enable tailing, all you need to do is select the check box Enable Tailing:
Once you're ready, click the Create button. Again, this will take you back to your Migrations panel, where you will see the following:
If you decide to finish the tailing process early, you can click Cancel Migration, which will stop the migration process.
Porting your application
Whether you choose to migrate your data in one go or start the tailing process, you should run a few checks to make sure that your data has been successfully migrated. These include data validation and structural compares.
At the same time, since you will be using a newer version of MongoDB, you'll need to make any necessary changes to your application that supports that database version. Consult the MongoDB release notes for database changes by version.
Once you've checked (and double checked) that your data is successfully stored in your new Databases for MongoDB deployment and that your application supports the newer database version, you can swap out your Compose for MongoDB connection string with your new Databases for MongoDB connection string. At this point, all your new reads and writes will take place in your new deployment, and you can deprovision Compose for MongoDB.
This quick guide is part of a series of articles that explains how to migrate your databases from Compose to IBM Cloud Databases—the latest generation of open-source databases on IBM Cloud. We focused on Compose for MongoDB in this article, but if you’re looking to migrate other databases from Compose to IBM Cloud Databases, we’ve got you covered in the following articles and documentation:
If you still have questions, reach out—our support team is always ready to lend a hand.