All Products
Search

This Product

    ApsaraDB for MongoDB:Migrate a self-managed standalone MongoDB database to ApsaraDB for MongoDB by using DTS

    Document Center

    ApsaraDB for MongoDB:Migrate a self-managed standalone MongoDB database to ApsaraDB for MongoDB by using DTS

    Last Updated:Mar 30, 2026

    Use Data Transmission Service (DTS) to migrate a self-managed MongoDB standalone deployment to ApsaraDB for MongoDB with minimal downtime.

    To migrate using MongoDB native tools instead, see Migrate a self-managed database to a standalone instance using MongoDB tools.

    For a full overview of migration options, see Data migration and synchronization.

    Prerequisites

    Before you begin, ensure that you have:

    • Checked version compatibility between your self-managed MongoDB database and ApsaraDB for MongoDB. See Overview of migration solutions

    • Provisioned an ApsaraDB for MongoDB instance with at least 10% more storage space than the source database currently uses

    • Converted the standalone instance to a single-node replica set — required to enable oplog, which DTS uses for incremental migration

    • Granted the required database account permissions. See Permissions required for database accounts

    • Added the DTS server CIDR blocks to the security settings of both the source and destination databases. See Add DTS server IP addresses to a whitelist

    Limitations

    • The config database is an internal system database. Do not migrate this database unless necessary. The admin and local databases cannot be used as source or destination

    • The destination ApsaraDB for MongoDB instance must not contain documents with the same primary key (_id) as the source. If conflicts exist, delete those documents from the destination before starting — otherwise data loss occurs

    • DTS writes data concurrently, so the destination database may use 5–10% more storage space than the source

    • For supported versions and storage engines, see Versions and storage engines. Check compatibility before migrating across versions or storage engines

    • Schedule the migration during off-peak hours to minimize impact on your services

    Billing

    Migration type Link configuration fees Data transfer cost
    Full data migration Free Charged when transferring data out of Alibaba Cloud over the Internet. See Billing overview

    Permissions required for database accounts

    Database Required permission
    Self-managed MongoDB (source) read on the database to be migrated
    ApsaraDB for MongoDB (destination) readWrite on the destination database

    To create accounts and grant permissions:

    Migrate the database

    Step 1: Open the Data Migration page

    Navigate to the migration task list using one of these entry points:

    From the DTS console

    1. Log on to the Data Transmission Service (DTS) console.

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

    3. In the upper-left corner, select the region where the migration instance will be located.

    From the DMS console

    Note

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

    1. Log on to the Data Management (DMS) console.

    2. In the top menu bar, choose Data + AI > Data Transmission (DTS) > Data Migration.

    3. To the right of Data Migration Tasks, select the target region.

    Step 2: Create a migration task

    Click Create Task to open the task configuration page.

    Step 3: Configure source and destination databases

    Warning

    After selecting the source and destination instances, read the limits shown at the top of the page carefully. Skipping this may cause the task to fail or result in data inconsistency.

    Configure the source database:

    Parameter Value
    Database type NoSQL Database > MongoDB
    Access method Select based on where the source database is deployed. This guide uses Public IP Address as an example. If you select a different access method, complete the corresponding preparations first
    Instance region Select the region where the source MongoDB database is located. If the region is not listed, select the geographically closest region
    Architecture Replica Set
    Migration method Select the incremental data migration method: Oplog (recommended when oplog is enabled — lower latency, faster log retrieval) or ChangeStreamChange Streams (when change streams are enabled). If the source is Amazon DocumentDB (non-elastic cluster), use ChangeStream only
    Endpoint type Standalone. This field appears only when Access method is Express Connect, VPN Gateway, or Smart Access Gateway, Public IP Address, or Cloud Enterprise Network (CEN)
    Domain name or IP The domain name or public IP address of the source MongoDB database
    Port number The service port of the source MongoDB database
    Authentication database The database that the source account belongs to. Defaults to admin
    Database account The account for the Mongos node. For Self-managed Database on ECS or Database Gateway access, enter the shard node account instead
    Database password The password for the database account
    Encryption Non-encrypted, SSL-encrypted, or Mongo Atlas SSL. Available options depend on the Access method and Architecture selected. Sharded Cluster + Oplog does not support SSL-encrypted. If using Replica Set with a non-Alibaba Cloud access method and SSL-encrypted, you can upload a CA certificate

    Configure the destination database:

    Parameter Value
    Database type MongoDB
    Access method Alibaba Cloud Instance
    Instance region The region where the destination ApsaraDB for MongoDB instance is located
    Replicate data across Alibaba Cloud accounts No (for migrations within the same account)
    Architecture The architecture of the destination ApsaraDB for MongoDB instance
    Instance ID The ID of the destination ApsaraDB for MongoDB instance
    Authentication database The database that the destination account belongs to. Defaults to admin
    Database name The name of the database in the destination instance that will receive the migrated data
    Database account The account for the destination ApsaraDB for MongoDB instance
    Database password The password for the database account
    Encryption Non-encrypted, SSL-encrypted, or Mongo Atlas SSL. Available options depend on Access method and Architecture. Sharded Cluster does not support SSL-encrypted

    Step 4: Test connectivity

    Click Test Connectivity and Proceed. In the CIDR Blocks of DTS Servers dialog box, click Test Connectivity.

    DTS server IP address ranges must be added to the security settings (whitelist) of both the source and destination databases before connectivity can succeed.

    Step 5: Configure objects to migrate

    On the Configure Objects page, set the following:

    Configuration Description
    Migration types Select Schema Migration and Full Data Migration
    Processing mode of conflicting tables Precheck and Report Errors: Checks for same-name collections in the destination. Reports an error during the precheck if conflicts exist, and the task does not start. Use object name mapping to resolve conflicts without deleting the destination collection. Ignore Errors and Proceed: Skips the check.
    Warning

    Selecting this may cause data inconsistency. If a destination document has the same primary key as a source document, the destination record is kept and the source record is not migrated
    Capitalization of object names in destination instance Configures case sensitivity for migrated object names (databases, collections). The default is DTS default policy. See Case sensitivity of object names in the destination database
    Source objects Click the databases or collections to migrate, then click Right arrow to move them to Selected Objects. Select at the database or collection level
    Selected objects To rename a migration object in the destination, right-click it in Selected Objects and configure the mapping. To remove an object, click it and then click image. To filter data by condition, right-click a collection and configure the filter. See Set filter conditions. If object name mapping is used, dependent objects may fail to migrate

    Step 6: Configure advanced settings

    Click Next: Advanced Settings and configure the following parameters:

    Configuration Description
    Dedicated cluster for task scheduling By default, DTS schedules tasks on a shared cluster. To use a dedicated cluster, purchase one first. See What is a DTS dedicated cluster?
    Retry time for failed connections How long DTS retries after a connection failure. Default: 720 minutes. Range: 10–1440 minutes. Set to more than 30 minutes. If DTS reconnects within this window, the task resumes automatically. Note: DTS charges during the retry period — set this based on your needs and release the DTS instance promptly after the source and destination instances are released
    Retry time for other issues How long DTS retries after non-connectivity errors (such as DDL or DML execution failures). Default: 10 minutes. Range: 1–1440 minutes. Set to more than 10 minutes. Must be less than Retry time for failed connections
    Enable throttling for full data migration Limits the queries per second (QPS) to the source, the RPS of Full Data Migration, and the data migration speed (MB/s). Available only when Full Data Migration is selected. You can also adjust throttling after the task starts
    Only one data type for primary key `_id` in a table of the data to be synchronized Specifies whether the _id field uses a single data type within each collection. Yes: DTS does not scan data types and migrates data for only one _id type per collection. No: DTS scans all data types and migrates all data. Select carefully — incorrect selection may cause data loss. Available only when Full Data Migration is selected
    Environment tag Optional. Tag the instance for identification
    Configure ETL Enable the extract, transform, and load (ETL) feature and enter data processing statements, or disable it. See What is ETL? and Configure ETL in a data migration or data synchronization task
    Monitoring and alerting Set an alert threshold and notification contacts. When a migration fails or latency exceeds the threshold, an alert is sent

    Step 7: Configure data validation

    Click Next: Data Validation to optionally set up a data validation task. See Configure data validation.

    Step 8: Run the precheck

    Click Next: Save Task Settings and Precheck.

    To preview the API parameters for this configuration, hover over the button and click Preview OpenAPI parameters.

    DTS runs a precheck before the migration starts. The task only begins after the precheck passes.

    • If the precheck fails, click View Details next to the failed item, fix the issue, and run the precheck again.

    • If a warning appears:

      • For non-ignorable items, click View Details, fix the issue, and run the precheck again.

      • For ignorable items, click Confirm Alert Details > Ignore > OK > Precheck Again. Ignored warnings may lead to data inconsistency.

    Step 9: Purchase the instance

    1. When Success Rate reaches 100%, click Next: Purchase Instance.

    2. On the Purchase page, select the instance class (link specification). The instance class affects migration speed. See Data migration link specifications.

      Parameter Description
      Resource group settings Select the resource group for this instance. Defaults to the default resource group. See What is Resource Management?
      Instance class Select a specification based on the required migration speed

    3. Read and accept Data Transmission Service (Pay-as-you-go) Service Terms.

    4. Click Purchase And Start, then click OK in the confirmation dialog.

    Verify the migration

    After the task starts, go to the Data Migration Tasks page to monitor progress. The page shows the current migration status and completion percentage.

    What's next