Upgrading an Amazon DocumentDB Cluster From Version 4.0 to 5.0 With DMS

This article reviews the process to upgrade an Amazon DocumentDB cluster from version 4.0 to 5.0 with DMS.

Amazon DocumentDB

Amazon DocumentDB is a fully managed, NoSQL database service provided by AWS. It is compatible with MongoDB, which is a popular open-source document database. Amazon DocumentDB is designed to be highly scalable, reliable, and performant, making it suitable for applications that require low-latency and high-throughput database operations.

AWS Database Migration Service

AWS DMS simplifies the process of database migration by providing an efficient and reliable solution for moving databases to AWS or between different database engines. It supports a wide range of database sources, including on-premises databases, databases running on AWS, and databases hosted on other cloud platforms.

Get Started

This demo assumes you have an existing DocumentDB cluster with version 4.0.

1. Create a new DocumentDB cluster with version 5.0. Use this link to help you get started.

2. Authenticate to your Amazon DocumentDB cluster 4.0 using the mongo shell and execute the following commands:

db.adminCommand({modifyChangeStreams: 1,
database: "db_name",
collection: "",
enable: true});

AWS DMS requires access to the cluster’s change streams.

3. Migrate your index’s with the Amazon DocumentDB Index Tool.

• First install PyMongo, click here
• Next, connect to Amazon DocumentDB using Python when TLS is enabled. Use this link to help you get started.
• Below is a sample of how I connected to my DocumentDB cluster 4.0 with python and imported some sample data

connection demonstration with hostname removed

• Install the Amazon DocumentDB Index Tool with this link
• Export indexes from source DocumentDB version 4.0 cluter [The image below is an example from my screen]

• Restore those indexes in your target Amazon DocumentDB version 5.0 cluster [The following image is an example of how to restore your indexes to your target cluster]

4. Create a replication instance.

• Navigate to Database Migration Service
• Select replication instances from left menu

• Click on the create replication instance button
• Name: (name of replication instance)
• Description: (description of instance)
• VPC: (use default or any specific VPC)
• For Multi AZ, select Dev or test workload (Single-AZ)
• Uncheck publicly accessible
• Click create

5. Update Security Groups.

• Copy the Private IP address of the new replication instance.
• Select the security group for your DocumentDB instances.
• Click edit inbound rules
• Click add rule
• Select TCP for type
• For port range select 27017
• For source, enter your replication instance’s private IP address you copied with a /32
• Save rules

6. Create Source endpoint.

• Navigate back to DMS
• Select endpoints on left menu
• Click on the create endpoint button
• Select source endpoint
• Endpoint identifier: (name of the endpoint)
• For source engine, select Amazon DocumentDB
• For access to endpoint database, select provide access information manually
• Server name: (server name of DocumentDB cluster with version 4.0) e.g. source.cluster-hsyfhsia.region.docdb.amazonaws.com
• Port: 27017
• For Secure Socket Layer (SSL) mode, select verify-full
• Click add new CA certificate
• Click choose file, and find and upload the Certificate Authority; this is the certificate used to connect to the cluster

• For certificate identifier, choose a name
• Click import certificate
• Enter in username and password used to connect to your DocumentDB cluster
• Enter in your database name
• Click create endpoint
• Test your connection to verify it was successfully setup

7. Create Target Endpoint

• Repeat the steps above to configure your DocumentDB version 5.0 cluster as the Target Endpoint

8. Create the Database Migration Task

• Click on the create task button
• Task identifier (name of task identifier)
• For replication instance, select the replication instance you created

• For source database endpoint, select your DocumentDB cluster version 4.0
• For target database endpoint, select your newly created DocumentDB cluster version 5.0
• For migration type, select Migrate Existing Data and Replicate Ongoing Changes

• For task settings, and under target table preparation mode, select do nothing
• For migration task startup configuration, choose automatically on create; this will automatically start the migration task once complete.

9. Monitor the migration task.

• Once the task has started, you can monitor the progress of Full Load and CDC replication on the individual collection with the Table Statistics tab

• AWS DMS has completed a full load migration of your source Amazon DocumentDB 4.0 cluster to your target Amazon DocumentDB 5.0 cluster and is now replicating change events

You are now ready to change your application’s database connection endpoint from your source Amazon DocumentDB 4.0 cluster to your target Amazon DocumentDB 5.0 cluster.

Matt Mendez is a dedicated and passionate IT professional with a strong desire to help people as a consultant. With expertise in AWS, Linux, Terraform, and Google Cloud. He has acquired valuable certifications in these areas. Having hands-on experience in working with leading cloud platforms such as AWS, Azure, and Google Cloud, as well as proficient in managing infrastructure using Terraform and Kubernetes.

Follow Matt on LinkedIn