Migrating Amazon DocumentDB Cluster across Regions: A step by step guide

As businesses expand globally and AWS continues to grow its regional footprint, some organizations need their database infrastructure to span multiple Regions. Organizations span Amazon DocumentDB (with MongoDB compatibility) clusters across AWS Regions to reduce latency by serving customers from the nearest AWS Regions, or to meet regulatory compliance requirements. You can also use Amazon DocumentDB Global Clusters to do cross-region migration with minimal downtime.

On July 14, 2025, Amazon DocumentDB expanded Global Clusters support from 5 to 10 secondary Regions. This enhancement allows organizations to deploy their document compatible databases across more regions worldwide, improving performance for globally distributed applications and providing greater flexibility for compliance and Disaster Recovery (DR) strategies.

Amazon DocumentDB is a serverless, fully managed, MongoDB API-compatible document database service that makes it easy and cost effective to operate critical document workloads at virtually any scale without managing infrastructure. Amazon DocumentDB serves tens of thousands of customers globally across all industries. You can enhance your applications with GenAI and machine learning (ML) capabilities using vector search for Amazon DocumentDB and integration with Amazon SageMaker Canvas.

Solution overview

In this post, you will learn to migrate a regional Amazon DocumentDB cluster from one AWS Region to another using the Global Cluster feature with low downtime and without performance impact.

This solution will incur Global Cluster costs for replicated write I/O, compute instances, and storage across regions based on your configuration. You can use the AWS Pricing Calculator to estimate the cost based on your configuration.

Below are the high-level steps to perform this migration:

1. Convert existing regional cluster into a global cluster by adding a Region
2. Perform the switchover and update the application configuration
3. Remove the global cluster setup

Prerequisites

Let’s consider an example scenario where we demonstrate how to migrate a regional Amazon DocumentDB cluster from ap-southeast-1 (Singapore) Region to ap-south-1 (Mumbai) using Global cluster setup through the AWS console

• Amazon DocumentDB 5.0 instance-based cluster in the source Region ap-southeast-1 . You can use an existing cluster or create a new one.
• VPC/subnet setup in the target Region ap-south-1
• Take a manual snapshot of cluster on source ap-southeast-1 Region
• Application is deployed in target Region ap-south-1

Convert the regional cluster into a Global Cluster

We will create a global cluster by converting the source regional cluster docdb-sgp in ap-southeast-1 into a global cluster by adding ap-south-1 as secondary Region.

1. From the Amazon DocumentDB console in ap-southeast-1, select the docdb-sgp cluster and from the Actions menu, select Add Region.
2. Choose the Secondary region as ap-south-1 and provide the global cluster identifier and secondary cluster identifier. For example, Global cluster identifier: docdb-migration-demo and Secondary cluster identifier: docdb-mum
3. Choose the DB instance class and Number of replica instances for your secondary cluster.
   We recommend selecting the same number of instances and instance class for your secondary cluster to ensure you have the same capacity available for your application in the new Region.
4. Enable Show advanced settings to select the network settings for your secondary Region cluster, including VPC details and subnet group. Ensure other settings match your primary cluster, such as encryption at rest settings.
   Note: You cannot change VPC, subnet groups and encryption settings after the cluster is created.
5. Select secondary cluster port number and cluster parameter group. Make sure your cluster parameter group have similar settings as source Region cluster.
6. Rest of the settings can be left to default and choose create cluster button

Wait for secondary Region to become active

The secondary Region will need some time to become available. Once ready, the docdb-migration-demo will have its primary cluster in the ap-southeast-1 Region and a secondary cluster in the ap-south-1 Region.

Data Replication happens from primary Region cluster ap-south-east-1 to secondary Region cluster in ap-south-1. It is important to confirm the replication lag by monitoring the GlobalClusterReplicationLag CloudWatch metric on secondary cluster doc-mum. This metric should be minimum (in milliseconds)

1. Navigate Amazon DocumentDB console on the secondary ap-south-1 Region.
2. On the doc-mum (secondary region cluster), select Monitoring tab to find GlobalClusterReplicationLag and choose view in metrics

Note: GlobalClusterReplicationLag metric is available on secondary clusters only

Perform the switchover

Once replication is synced (replica lag in millisecond range), we are ready to promote the secondary cluster in ap-south-1 to primary. As both the Regions are healthy, we will perform a Switchover to complete our migration.

1. Stop application writes to the source Region cluster.
2. Using AWS DocumentDB console in any Region, select the global cluster docdb-migration-demo and from the Actions menu choose Switchover or Failover.
3. Select the switchover and new primary Region cluster ap-south-1 Region cluster and hit the Confirm button.
   The switchover process takes few minutes to complete to prevent data loss. During this period, the application cannot perform any operation on the database (downtime).
   
4. Wait for status to become available for primary and secondary clusters. After switchover step completion, cluster is ap-south-1 Region becomes the new primary and the cluster in ap-southeast-1 Region becomes secondary.
   

Update application connection configuration

1. Locate connection string for the ap-south-1 cluster docdb-mum, for more information see Finding a cluster’s endpoints.
2. Update the application connection configuration to use the docdb-mum cluster endpoint and start the application in ap-south-1 Region. Don’t use global cluster endpoint.
3. Make sure application is working fine and all the checkouts are good. Now you have successfully migrated to ap-south-1 Region.
4. The secondary Region cluster in ap-southeast-1 is now unused. But, before deleting the secondary Region, we recommend keeping this setup running for a few days in case you need to switch back to the old region ap-southeast-1

To roll back to the previous primary Region ap-southeast-1, we can initiate a switchover from ap-south-1 to ap-southeast-1 and update the application endpoint, provided the ap-southeast-1 cluster or the global cluster configuration exists.

Remove Global Cluster Setup

We can remove the global cluster setup using the following steps

1. From the Amazon DocumentDB Console in ap-southeast-1 Region. Select the current secondary Region cluster docdb-sgp and from the Actions choose Remove from global and select Remove and Promote. This step removes docdb-sgp cluster from Global cluster setup and promotes it as standalone cluster.
   
2. Once docdb-sgp is removed from the Global cluster, only the docdb-mum cluster will remain in the global cluster with the role of primary cluster.
   
3. Remove the primary cluster in docdb-mum from Global cluster setup. Choose the current primary cluster docdb-mum and from Actions – Select Remove and Promote
   
4. Now, cluster in ap-south-1 will be run standalone cluster.
   

Cleanup

1. Delete the Global Cluster docdb-migration-demo, which has 0 Regions
2. Navigate to the ap-southeast-1 Region and delete the old cluster docdb-sgp

Note: You may need to disable the Deletion protection if it is enabled.

Conclusion

You can use Amazon DocumentDB Global Clusters to migrate your database between AWS Regions with minimum downtime and operational complexity. Whether you’re moving for performance, compliance, or disaster recovery, this architecture supports scalable, cross-regional Amazon DocumentDB deployments with confidence.

For more information about recent launches and blog posts, see Amazon DocumentDB resources.

About the authors