Migrate a self-managed MongoDB database (sharded cluster architecture) to ApsaraDB for MongoDB (replica set architecture or sharded cluster architecture)

Prerequisites

• An ApsaraDB for MongoDB instance, either with replica set or sharded cluster architecture, has been successfully created. For more information, see how to create a replica set instance or how to create a sharded cluster instance.

  Important

  • It is advisable to ensure that the target ApsaraDB for MongoDB instance has a storage capacity at least 10% greater than that used by the source self-managed MongoDB instance.

  • For a list of supported versions, see the migration plan overview.

• Accounts with consistent credentials have been created for all shard nodes of the source self-managed MongoDB instance.

• If the target MongoDB is a sharded cluster architecture instance:

  • Ensure that the shard nodes in the target sharded cluster instance have sufficient storage space.

    Note

    For instance, if the second shard node of the self-managed database uses the most storage space (500 GB), then each shard node in the target instance must have more than 500 GB of storage space.

  • Create the necessary sharded databases and collections, set up data sharding, activate the balancer, and initiate pre-sharding within your ApsaraDB for MongoDB instance (sharded cluster architecture) according to your business needs. For more information, see how to optimize shard performance through data sharding and how to address uneven data distribution in a MongoDB sharded cluster architecture.

    Note

    Configuring data sharding helps prevent data from being migrated to the same shard, which could hinder optimal cluster performance. Enabling the balancer and pre-sharding can help avoid data skew.

Notes

Pricing

Task steps

Permissions required for database accounts

For more information about how to create a database account and grant permissions, see the following topics:

• Self-managed MongoDB database: db.createUser()

• ApsaraDB for MongoDB instance: Manage user permissions on MongoDB databases

Preparations

1. Required: Disable the balancer of the self-managed MongoDB database. This prevents the impact of chunk migration on data consistency. For more information, see Manage the ApsaraDB for MongoDB balancer.

   Warning

   If the balancer is not disabled, chunk migration affects the consistency of the data read by DTS.

2. Delete the orphaned documents that are generated due to chunk migration failures from the self-managed MongoDB database.

   Note

   If you do not delete the orphaned documents, the migration performance will be compromised. In addition, some documents may have duplicate _id values and data that you do not want to migrate may be migrated.

   1. Download the cleanupOrphaned.js file.

      wget "https://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/attach/120562/cn_zh/1564451237979/cleanupOrphaned.js"

   2. Replace test in the cleanupOrphaned.js file with the name of the database from which you want to delete orphaned documents.

      Note

      If you want to delete orphaned documents from multiple databases, repeat Substep b and Substep c in Step 2.

      

   3. Run the following command on a shard to delete the orphaned documents from all collections in the specified database:

      Note

      You must repeat this step on each shard.

      mongo --host <Shardhost> --port <Primaryport>  --authenticationDatabase <database> -u <username> -p <password> cleanupOrphaned.js

      Note

      • <Shardhost>: the IP address of the shard.

      • <Primaryport>: the service port of the primary node in the shard.

      • <database>: the name of the database to which the database account belongs.

      • <username>: the account that is used to log on to the self-managed MongoDB database.

      • <password>: the password that is used to log on to the self-managed MongoDB database.

      Example:

      In this example, a self-managed MongoDB database has three shards, and you must delete the orphaned documents on each shard.

      mongo --host 172.16.1.10 --port 27018  --authenticationDatabase admin -u dtstest -p 'Test123456' cleanupOrphaned.js

      mongo --host 172.16.1.11 --port 27021 --authenticationDatabase admin -u dtstest -p 'Test123456' cleanupOrphaned.js

      mongo --host 172.16.1.12 --port 27024  --authenticationDatabase admin -u dtstest -p 'Test123456' cleanupOrphaned.js

3. Create databases and collections to be sharded in the destination ApsaraDB for MongoDB instance, and configure data sharding based on your business requirements. For more information, see Configure sharding to maximize the performance of shards.

   Note

   If you configure data sharding before you start data migration, data in the self-managed MongoDB database is evenly migrated to the shards in the destination sharded cluster instance. This prevents the overloading of a single shard.

Procedure

1. Use one of the following methods to go to the Data Migration page and select the region in which the data migration instance resides.

   DTS console

   DMS console

   1. Log on to the DTS console.

   2. In the left-side navigation pane, click Data Migration.

   3. In the upper-left corner of the page, select the region in which the data migration instance resides.

   Note

   The actual operation may vary based on the mode and layout of the DMS console. For more information, see Simple mode and Customize the layout and style of the DMS console.

   1. Log on to the DMS console.

   2. In the top navigation bar, move the pointer over Data Development > DTS (DTS) > Data Migration .

   3. From the drop-down list to the right of Data Migration Tasks, select the region in which the data synchronization instance resides.

2. Click Create Task to go to the task configuration page.

3. Configure the source and destination databases. The following table describes the parameters.

   Warning

   After you configure the source and destination databases, we recommend that you read the Limits that are displayed in the upper part of the page. Otherwise, the task may fail or data inconsistency may occur.

   Category	Configuration	Description

   Category	Configuration	Description
   None	Task Name	The name of the DTS task. DTS automatically generates a task name. We recommend that you specify an informative name that makes it easy to identify the task. You do not need to specify a unique task name.
   Source Database	Select Existing Connection	The instance that you want to use. You can choose whether to use an existing instance based on your business requirements. If you select an existing instance, DTS automatically populates the parameters for the database. If you do not use an existing instance, you must configure the database information below. Note You can register a database with DTS on the Database Connections page or the new configuration page. For more information, see Manage database connections. In the DMS console, you can select an existing database from the Select a DMS database instance. drop-down list. You can also click Add DMS Database Instance or go back to the homepage of the DMS console to register a database with DMS. For more information, see Register an Alibaba Cloud database instance and Register a database hosted on a third-party cloud service or a self-managed database.
   	Database Type	Select MongoDB.
   	Access Method	Select based on the deployment location of the source database. This example uses Public IP Address as an example to describe the configuration process. Note If you choose another method to connect to a self-managed database, you also need to perform the corresponding preparations. For more information, see Overview of preparations.
   	Instance Region	Select the region where the self-managed MongoDB database resides. Note If the region where the self-managed MongoDB database resides is not available in the options, you can select the region closest to the database.
   	Architecture	Select Sharded Cluster. Note The Sharded Cluster option appears only when you connect to a self-managed MongoDB using Express Connect, VPN Gateway, or Smart Access Gateway, Public IP Address, or Cloud Enterprise Network (CEN).
   	Migration Method	Select the method for incremental data migration based on your actual situation. Oplog (recommended): If the source database has enabled Oplog, this option is supported. Note Local self-managed MongoDB and ApsaraDB for MongoDB have Oplog enabled by default. When migrating incremental data using this method, the delay of the incremental migration task is small (the speed of pulling logs is fast). Therefore, it is recommended to select Oplog. ChangeStream: If the source database has enabled Change Streams (Change Streams), this option is supported. Note When the source database is Amazon DocumentDB (non-elastic cluster), only ChangeStream is supported. When the Architecture of the source database is selected as Sharded Cluster, there is no need to fill in the Shard account and Shard password.
   	Endpoint Type	Select Standalone or Multi-node based on your actual situation. Note This configuration item appears only when you connect to a self-managed MongoDB using Express Connect, VPN Gateway, or Smart Access Gateway, Public IP Address, or Cloud Enterprise Network (CEN).
   	Domain Name or IP	Enter the domain name or IP address of a single Mongos node in the self-managed MongoDB database. In this example, enter the public IP address. Note This configuration item appears only when Endpoint Type is Standalone. Enter the Domain Name or IP and Port Number of any Mongos node.
   	Port Number	Enter the service port of the self-managed MongoDB database. Note This configuration item appears only when Endpoint Type is Standalone. The service ports of each Mongos node must be open to the public network.
   	Endpoint	Enter the connection address of the self-managed MongoDB database. Note This configuration item appears only when the Endpoint Type is Multi-node. The format is <IP>:<Port>, where <IP> is the domain name or IP address. It is recommended to use a domain name that can be resolved by the public network. Multiple connection addresses can be separated by pressing the Enter key.
   	Authentication Database	Enter the name of the database to which the database account in the self-managed MongoDB belongs. If it has not been modified, the default is admin.
   	Database Account	Enter the account of the corresponding Mongos node in the self-managed MongoDB. For permission requirements, see Permissions required for database accounts. Note If the Access Method of the self-managed MongoDB is Self-managed Database on ECS or Database Gateway, enter the account of the shard node.
   	Database Password	The password that is used to access the database instance.
   	Access to Multiple Shard Nodes	The information that is used to access the shard nodes of the self-managed MongoDB database. Note This parameter is available only if the self-managed MongoDB database is the source database, the Architecture parameter is set to Sharded Cluster, and the Endpoint Type parameter is set to Multi-node. Click Add to the right of Access to Multiple Shard Nodes. In the Shard Node Endpoint field, enter the endpoint of a shard node of the self-managed MongoDB database. Note An endpoint is in the <IP>:<Port> format. Replace <IP> with a domain name or an IP address. We recommend that you use a domain name that is publicly resolvable. Separate multiple endpoints with line feeds. Repeat the preceding steps to configure the access information for each shard node.
   	Shard access information (IP:Port)	Enter the IP address and port information of the shard node in the self-managed MongoDB database. The format is <IP>:<Port>. Note This configuration item appears only when Endpoint Type is Standalone. Multiple shard node information can be separated by commas (,).
   	Shard account	Enter the shard account of the self-managed MongoDB database.
   	Shard password	Enter the password of the shard account in the self-managed MongoDB database.
   	Encryption	Specifies whether to encrypt the connection to the source database. You can select Non-encrypted, SSL-encrypted, or Mongo Atlas SSL based on your business requirements. The options available for the Encryption parameter are determined by the values selected for the Access Method and Architecture parameters. The options displayed in the DTS console prevail. Note If the Architecture parameter is set to Sharded Cluster, and the Migration Method parameter is set to Oplog for the ApsaraDB for MongoDB database, the Encryption parameter SSL-encrypted is unavailable. If the source database is a self-managed MongoDB database that uses the Replica Set architecture, the Access Method parameter is not set to Alibaba Cloud Instance, and the Encryption parameter is set to SSL-encrypted, you can upload a certification authority (CA) certificate to verify the connection to the source database.
   Destination Database	Select Existing Connection	The instance that you want to use. You can choose whether to use an existing instance based on your business requirements. If you select an existing instance, DTS automatically populates the parameters for the database. If you do not use an existing instance, you must configure the database information below. Note You can register a database with DTS on the Database Connections page or the new configuration page. For more information, see Manage database connections. In the DMS console, you can select an existing database from the Select a DMS database instance. drop-down list. You can also click Add DMS Database Instance or go back to the homepage of the DMS console to register a database with DMS. For more information, see Register an Alibaba Cloud database instance and Register a database hosted on a third-party cloud service or a self-managed database.
   	Database Type	Select MongoDB.
   	Access Method	Select Alibaba Cloud Instance.
   	Instance Region	Select the region where the target ```html ApsaraDB for MongoDB instance resides.
   	Replicate Data Across Alibaba Cloud Accounts	In this example, a database instance of the current Alibaba Cloud account is used. Select No.
   	Architecture	Select the architecture type to which the target ApsaraDB for MongoDB belongs.
   	Instance ID	Select the ID of the target ApsaraDB for MongoDB instance.
   	Authentication Database	Enter the name of the database to which the database account of the target ApsaraDB for MongoDB instance belongs. If it has not been modified, the default is admin.
   	Database Name	Enter the name of the database to which the migration object in the target ApsaraDB for MongoDB instance belongs.
   	Database Account	Enter the database account of the target ApsaraDB for MongoDB instance. For permission requirements, see Permissions required for database accounts.
   	Database Password	The password that is used to access the database instance.
   	Encryption	Specifies whether to encrypt the connection to the destination database. You can select Non-encrypted, SSL-encrypted, or Mongo Atlas SSL based on your business requirements. The options available for the Encryption parameter are determined by the values selected for the Access Method and Architecture parameters. The options displayed in the DTS console prevail. Note If the destination database is an ApsaraDB for MongoDB instance and the Architecture parameter is set to Sharded Cluster, the Encryption parameter SSL-encrypted is unavailable. If the destination database is a self-managed MongoDB database that uses the Replica Set architecture, the Access Method parameter is not set to Alibaba Cloud Instance, and the Encryption parameter is set to SSL-encrypted, you can upload a CA certificate to verify the connection to the destination database.

4. In the lower part of the page, click Test Connectivity and Proceed.

   Note

   • Make sure that the CIDR blocks of DTS servers can be automatically or manually added to the security settings of the source and destination databases to allow access from DTS servers. For more information, see Add the CIDR blocks of DTS servers.

   • If the source or destination database is a self-managed database and its Access Method is not set to Alibaba Cloud Instance, click Test Connectivity in the CIDR Blocks of DTS Servers dialog box.

5. Configure the objects to be migrated.

   1. On the Configure Objects page, configure the objects that you want to migrate.

      Configuration	Description

      Configuration	Description
      Migration Types	To perform only full data migration, select Schema Migration and Full Data Migration. To ensure service continuity during data migration, select Schema Migration, Full Data Migration, and Incremental Data Migration. Note If you do not select Schema Migration, make sure a database and a table are created in the destination database to receive data and the object name mapping feature is enabled in Selected Objects. If you do not select Incremental Data Migration, we recommend that you do not write data to the source database during data migration. This ensures data consistency between the source and destination databases.
      Processing Mode of Conflicting Tables	Precheck and Report Errors: checks whether the destination database contains tables that use the same names as tables in the source database. If the source and destination databases do not contain tables that have identical table names, the precheck is passed. Otherwise, an error is returned during the precheck and the data migration task cannot be started. Note If the source and destination databases contain tables with identical names and the tables in the destination database cannot be deleted or renamed, you can use the object name mapping feature to rename the tables that are migrated to the destination database. For more information, see Map object names. Ignore Errors and Proceed: skips the precheck for identical table names in the source and destination databases. Warning If you select Ignore Errors and Proceed, data inconsistency may occur and your business may be exposed to the following potential risks: If the source and destination databases have the same schema, and a data record has the same primary key as an existing data record in the destination database, the following scenarios may occur: During full data migration, DTS does not migrate the data record to the destination database. The existing data record in the destination database is retained. During incremental data migration, DTS migrates the data record to the destination database. The existing data record in the destination database is overwritten. If the source and destination databases have different schemas, only specific columns are migrated or the data migration task fails. Proceed with caution.
      Capitalization of Object Names in Destination Instance	The capitalization of database names and collection names in the destination instance. By default, DTS default policy is selected. You can select another option to ensure that the capitalization of object names is the same as that of the source or destination database. For more information, see Specify the capitalization of object names in the destination instance.
      Source Objects	Select one or more objects from the Source Objects section. Click the icon to add the objects to the Selected Objects section. Note Migration object selection granularity is at the Collection or Database level.
      Selected Objects	To specify the name of an object to be migrated in the destination instance or specify the object to receive data in the destination instance, right-click the object in the Selected Objects section. For more information, see Map object names. To remove one or more objects that are selected for migration, click the objects in the Selected Objects section and then click the icon to move the objects to the Source Objects section. Note If you need to perform incremental migration operations at the database or collection level, right-click the object you want to migrate within the Selected Objects list and choose your option from the pop-up dialog box. If you need to establish filter conditions for data (supported during full migration but not during incremental migration), right-click the desired table in the Selected Objects list and configure them in the dialog box that appears. For details on how to configure these settings, see Set filter conditions. If the object name mapping feature (specifying the database or collection to receive data) is used, it may cause migration failures for other objects that depend on this object.

   2. Click Next: Advanced Settings to configure advanced settings.

      Configuration	Description

      Configuration	Description
      Dedicated Cluster for Task Scheduling	By default, DTS schedules tasks on shared clusters, and there's no need for you to configure this parameter. However, you can opt to purchase a dedicated cluster with specific specifications for running DTS migration tasks. For more information, see What is a DTS dedicated cluster.
      Retry Time for Failed Connections	The retry time range for failed connections. If the source or destination database fails to be connected after the data migration task is started, DTS immediately retries a connection within the retry time range. Valid values: 10 to 1440. Unit: minutes. Default value: 720. We recommend that you set the parameter to a value greater than 30. If DTS is reconnected to the source and destination databases within the specified retry time range, DTS resumes the data migration task. Otherwise, the data migration task fails. Note If you specify different retry time ranges for multiple data migration tasks that share the same source or destination database, the value that is specified later takes precedence. When DTS retries a connection, you are charged for the DTS instance. We recommend that you specify the retry time range based on your business requirements. You can also release the DTS instance at the earliest opportunity after the source database and destination instance are released.
      Retry Time for Other Issues	The retry time range for other issues. For example, if DDL or DML operations fail to be performed after the data migration task is started, DTS immediately retries the operations within the retry time range. Valid values: 1 to 1440. Unit: minutes. Default value: 10. We recommend that you set the parameter to a value greater than 10. If the failed operations are successfully performed within the specified retry time range, DTS resumes the data migration task. Otherwise, the data migration task fails. Important The value of the Retry Time for Other Issues parameter must be smaller than the value of the Retry Time for Failed Connections parameter.
      Enable Throttling for Full Data Migration	Specifies whether to enable throttling for full data migration. During full data migration, DTS uses the read and write resources of the source and destination databases. This may increase the loads of the database servers. You can enable throttling for full data migration based on your business requirements. To configure throttling, you must configure the Queries per second (QPS) to the source database, RPS of Full Data Migration, and Data migration speed for full migration (MB/s) parameters. This reduces the loads of the destination database server. Note You can configure this parameter only if you select Full Data Migration for the Migration Types parameter.
      Only one data type for primary key _id in a single table	For the data to be migrated, whether the data type of the primary key _id is unique within the same collection. Note This configuration is only available when the Migration Types is set to Full Data Migration. Yes: Unique. DTS does not scan the data type of the primary key in the source data during the full migration phase from the source database. No: Indicates non-uniqueness. During the full migration phase, DTS scans the data type of the primary key in the source data slated for migration from the source database.
      Enable Throttling for Incremental Data Migration	Specifies whether to enable throttling for incremental data migration. To configure throttling, you must configure the RPS of Incremental Data Migration and Data migration speed for incremental migration (MB/s) parameters. This reduces the loads of the destination database server. Note You can configure this parameter only if you select Incremental Data Migration for the Migration Types parameter.
      Environment Tag	Select an environment tag to identify the instance as needed. In this example, no tag is selected.
      Configure ETL	Specifies whether to enable the extract, transform, and load (ETL) feature. For more information, see What is ETL? Valid values: Yes: configures the ETL feature. You can enter data processing statements in the code editor. For more information, see Configure ETL in a data migration or data synchronization task. No: does not configure the ETL feature.
      Monitoring and Alerting	Specifies whether to configure alerting for the data migration task. If the task fails or the migration latency exceeds the specified threshold, the alert contacts receive notifications. Valid values: No: does not configure alerting. Yes: configures alerting. In this case, you must also configure the alert threshold and alert notification settings. For more information, see the Configure monitoring and alerting when you create a DTS task section of the Configure monitoring and alerting topic.

   3. Click Next Step: Data Verification to configure the data verification task.

      For more information about how to use the data verification feature, see Configure a data verification task.

6. Save the task settings and run a precheck.

   1. To view the parameters to be specified when you call the relevant API operation to configure the DTS task, move the pointer over Next: Save Task Settings and Precheck and click Preview OpenAPI parameters.

   2. If you do not need to view or have viewed the parameters, click Next: Save Task Settings and Precheck in the lower part of the page.

   Note

   1. Before you can start the data migration task, DTS performs a precheck. You can start the data migration task only after the task passes the precheck.

   2. If the task fails to pass the precheck, click View Details next to each failed item. After you analyze the causes based on the check results, troubleshoot the issues. Then, run a precheck again.

   3. If an alert is triggered for an item during the precheck:

      1. If an alert item cannot be ignored, click View Details next to the failed item and troubleshoot the issues. Then, run a precheck again.

      2. If the alert item can be ignored, click Confirm Alert Details. In the View Details dialog box, click Ignore. In the message that appears, click OK. Then, click Precheck Again to run a precheck again. If you ignore the alert item, data inconsistency may occur, and your business may be exposed to potential risks.

7. Purchase an instance.

   1. Wait until Success Rate becomes 100%. Then, click Next: Purchase Instance.

   2. On the Purchase Instance page, configure the Instance Class parameter for the data migration instance. The following table describes the parameters.

      Section	Parameter	Description

      Section	Parameter	Description
      New Instance Class	Resource Group	The resource group to which the data migration instance belongs. Default value: default resource group. For more information, see What is Resource Management?
      	Instance Class	DTS provides instance classes that vary in the migration speed. You can select an instance class based on your business scenario. For more information, see Instance classes of data migration instances.

   3. Read and agree to Data Transmission Service (Pay-as-you-go) Service Terms by selecting the check box.

   4. Click Buy and Start. In the message that appears, click OK.

      You can view the progress of the task on the Data Migration page.

8. (Optional): If the Access Method for your self-managed MongoDB is either Self-managed Database on ECS or Database Gateway, you should also follow steps 1 to 7 to create migration tasks for the remaining shard nodes.

9. Complete the migration task.

   • Full data migration

     It is recommended not to manually interrupt a task during full data migration, as this may result in incomplete data transfer to the destination database. It is best to allow the full data migration task to conclude automatically once complete.

   • Incremental data migration

     The migration task will not stop automatically; you must manually terminate it.

     Note

     Choose an optimal time to manually stop the migration task, such as off-peak hours or when you are prepared to transition your operations to the MongoDB instance.

     1. Wait until the Running of the migration tasks for all shard nodes reaches Incremental Data Migration, and the Operation Info indicates a Undelayed status. Cease writing to the source database for a few minutes. The status may then display the delay time.

     2. Wait for the Incremental Data Migration status of all shard node migration tasks to show Undelayed once again before manually stopping the migration task.

10. Switch your workloads to the destination ApsaraDB for MongoDB instance.