Migrate MongoDB to Azure DocumentDB by using Azure Database Migration Service

In this tutorial, use the Azure Database Migration Service (DMS) experience in the Azure portal to create and manage migration jobs from an on-premises or cloud instance of MongoDB to Azure DocumentDB. DMS supports online and offline migrations, public and private connectivity, and collection-level migration settings.

The portal experience uses the same managed migration capabilities as the Azure DocumentDB Migration Extension. Use this approach when you want to create and monitor migration jobs without installing Visual Studio Code extensions.

Prerequisites

  • An Azure subscription. If you don't have an Azure subscription, create a free account.

  • An existing Azure DocumentDB cluster

Before starting the migration, prepare your Azure DocumentDB account and your existing MongoDB instance for migration.

MongoDB instance (source)

  • Complete the premigration assessment to check for incompatibilities and warnings between your source instance and target account.
  • Add a user with readAnyDatabase and clusterMonitor permissions, unless one already exists. Use this credential while creating the migration job.

Azure DocumentDB (target)

  • Gather the Azure DocumentDB account's credentials.
  • Ensure user has createCollection, dropCollection, createIndex, insert, and listCollections permissions.

Minimum required permissions

Use the following minimum roles to create and run migration jobs.

Minimum role Scope Applies to connectivity mode Purpose
Reader Subscription Public and private List subscriptions and resource groups. Required for each migration job.
Azure Database Migration Service Contributor Resource group Public and private Create Azure Database Migration Service (DMS). You don't need to create a new DMS for every migration. One DMS per region is enough.
Contributor Subscription Public and private Register DMS in the subscription. This registration is a one-time activity and can be delegated to another user.
User Access Administrator Virtual network Private only Assign the Network Contributor role to the DMS object principal. This assignment is a one-time activity per virtual network and can be delegated to another user.
Contributor Azure DocumentDB Public and private Trigger the migration job.

For provider registration details, see Register Microsoft.DataMigration resource provider in your subscription.

Important

Microsoft Entra ID authentication isn't currently supported in migration jobs. Use native DocumentDB authentication.

Perform the migration

For planning guidance on migration sizing, speed, and cutover, see Migration best practices.

Open the DMS migration experience

  1. Sign in to the Azure portal.

  2. Select Create a resource, search for Azure Database Migration Service, and then select Create.

  3. On Select migration scenario and Database Migration Service, configure the migration scenario:

    • For Source server type, select MongoDB.
    • For Target server type, select Azure DocumentDB (with MongoDB compatibility).
    • For Database Migration Service, select Database Migration Service.

    Screenshot of the Azure portal showing MongoDB as the source, Azure DocumentDB as the target, and Database Migration Service as the migration service.

  4. On the Basics tab, configure the DMS resource:

    • Select the Subscription and Resource group.
    • For Location, select the same Azure region as the target Azure DocumentDB account.
    • Enter a unique Migration service name.

    Screenshot of the Basics tab for creating an Azure Database Migration Service resource.

  5. Select Review + create, and then select Create after validation succeeds.

  6. After deployment finishes, select Go to resource.

  7. On the DMS resource overview, select New Migration.

    Screenshot of an Azure Database Migration Service resource overview with the New Migration action.

Create a migration job

Use a migration job to migrate a group of collections from the source to the destination Azure DocumentDB.

Before the migration wizard can retrieve the available databases and collections, configure access for the Azure portal middleware:

  1. Review the portal middleware IP addresses displayed by the wizard.

  2. Choose the option that matches your environment:

    • Select Firewall access configured after adding the displayed IP addresses to the firewall allow lists for both the source MongoDB cluster and target Azure DocumentDB cluster.
    • Select Private connectivity or restricted firewall access if either connection is private or you can't change the firewall rules. For this option, provide the databases and collections to migrate by using the JSON configuration in Step 4.

  3. Select Continue.

Screenshot of the MongoDB Migration Wizard showing portal middleware IP addresses and firewall access options.

Step 1: Create job

In this step, enter the basic details for the job.

  • Job Name: Enter a user-friendly name to identify the migration job.

  • Migration Mode: Select the migration mode that's most appropriate for your use case.

    • Online migration copies collection data and ensures updates are also replicated during the process. This method minimizes downtime, so you can keep operations running for business continuity. Use this option when ongoing operations are crucial, and reducing downtime is a priority.
    • Offline migration captures a snapshot of the database at the beginning, offering a simpler and predictable approach. It works well when using a static copy of the database is acceptable, and real-time updates aren't essential.

    Important

    To ensure successful online migrations from MongoDB, you must enable ChangeStream on the source MongoDB server. Without ChangeStream, the migration process doesn't capture any modifications made to the data after the initial migration. Therefore, use the online migration mode only if ChangeStream is enabled on your source MongoDB server.

  • Connectivity: Depending on your organization's security mandate and network setup, choose from Public and Private.

    • Use Public when the source and target servers are accessible over the internet through public IPs. It enables support for services that require external accessibility.
    • Use Private when either the source or target servers are accessible exclusively through private IPs within a virtual network. It enhances security by eliminating exposure to the public internet.

Select Next to continue.

Screenshot of the create job step in the Azure portal migration wizard.

Step 2: Select target

Select an existing Azure DocumentDB account and provide its connection string.

  1. Select the subscription, resource group, and Azure DocumentDB account from the dropdowns.

  2. Enter the connection string to the Azure DocumentDB account.

  3. Select Next to continue.

Screenshot of the select target step in the Azure portal migration wizard.

Step 3: Configure connectivity

This screen depends on the connectivity mode you chose in Step 1.

Use the following steps if you selected Public as the connectivity mode in the migration wizard:

  1. Note the static IP addresses displayed in the wizard.

  2. Add these IP addresses to the firewall allow list on your source MongoDB server.

  3. Add these IP addresses to the Azure DocumentDB firewall.

Screenshot of the public connectivity configuration step in the Azure portal migration wizard.

Use the following steps if you selected Private as the connectivity mode in the migration wizard:

  1. In Virtual network, select the subscription, resource group, virtual network, and subnet for the required network path. Depending on the selected topology, the wizard shows Source, Target, Common, or Spoke virtual network details.

  2. In DMS configuration, select a CIDR range that doesn't overlap with your virtual networks or any reachable on-premises address space.

  3. In Enable Virtual Network Integration, run the PowerShell command or commands shown in the wizard to assign the Network Contributor role to the DMS service principal for the relevant virtual network or networks. If you already completed this step for a previous migration on the same virtual network, you don't need to repeat it.

Screenshot of the private connectivity configuration step in the Azure portal migration wizard.

For more information, see Public connectivity, Private connectivity, and Troubleshoot connectivity.

Select Next to continue.

Step 4: Select collections

Select the collections to include in the migration job. Use the search options to choose from the list of collections. Collections that already exist in the target are automatically marked Yes in the Exists in Target column.

Make sure to select all collections you want to include because you can't add collections after creating the migration job.

Select Next to continue.

Screenshot of the select collections step in the Azure portal migration wizard.

If a private endpoint is enabled or the Azure portal middleware can't connect to the source or target, the wizard might display an error instead of retrieving the collection list. You can still provide the collections by using either of these options:

  • In JSON view, upload a JSON file that lists the collections to migrate.
  • In Table view, enter a collection in database.collection format under Add Collection, and then select Add. Repeat this step to add each collection individually.

For JSON view, use an array with one object for each collection:

[
  {
    "sourceDatabase": "myDatabase",
    "sourceCollection": "myCollection"
  },
  {
    "sourceDatabase": "myDatabase",
    "sourceCollection": "anotherCollection"
  }
]

Screenshot of the Add Collection field in Table view, with a field for a collection in database dot collection format and an Add button.

Step 5: Configure collections

Configure how each selected collection is migrated to the target. For each collection, set the following options:

  • Overwrite target collection: Specify whether to overwrite a collection that already exists in the target. The Sharding and Indexing options apply only when you set Overwrite target collection to Yes.
  • Sharding strategy: Choose whether to shard the target collection or leave it unsharded. When you shard the target collection, it uses the same shard key as the source collection.
  • Indexing strategy: Choose how indexes are built on the target collection:
    • Do not create indexes: Skip index creation.
    • Copy indexes from source: Copy all indexes from the source collection. Unique indexes are copied before the initial data load, and nonunique indexes are copied after the initial data load.

Use the inline editor to configure these settings for individual collections, or select Bulk Update to apply the same settings to multiple collections.

Select Next to continue.

Screenshot of the configure collections step in the Azure portal migration wizard.

Step 6: Confirm and start

Review the migration job details before selecting Start Migration. If you need to update the details, use the Edit Details button.

After you create the migration job, you're automatically redirected to the View Existing Jobs page.

Azure Database Migration Service runs the data migration tasks. You don't need to stay connected to the source and target environments during the migration. The dashboard updates the status frequently.

Monitor existing migration jobs

On the DMS resource overview, locate the Monitor migrations card, and then select Monitor migrations. Select a migration job to view its status and collection-level details.

Screenshot of an Azure Database Migration Service resource overview with the Monitor migrations action.

The status automatically updates at frequent intervals. Offline jobs automatically complete once the selected collection snapshots are copied to target. However, you need to manually cut over the online migrations.

You can Pause a migration job to temporarily halt it at a logical point. When you're ready to continue, select Resume to pick up from where the job stopped.

To view the collection-wise status, select a row from the table.

Screenshot showing collection-level status for an offline migration in the Azure portal.

Monitor online migrations

Online migrations, unlike offline migrations, don't automatically complete. Instead, they run continuously until you manually finalize them by selecting Cutover.

To complete the online migration, follow these steps in the given order:

  1. The Cutover button is enabled once the initial data load finishes for all collections. At this stage, the job is in the replication phase, continuously copying updates from the source instance to the target instance to keep it up-to-date with the latest changes.

  2. When ready to perform the migration cutover, stop all incoming transactions to the source collections you're migrating.

  3. The Time Since Last Change shows the time gap between the last update and current time.

  4. Monitor the replication changes in the table and wait until the Replication Changes Played metric stabilizes. A stable Replication Changes Played metric indicates that all updates from the source are successfully copied to the target.

  5. Select Cutover when the replication gap is minimal for all collections and the Replication Changes Played metric is stable.

Screenshot showing collection-level status for an online migration in the Azure portal.

  1. Wait for the migration job to complete, which indicates that all source changes are synchronized to the target.

  2. Before declaring the migration complete, manually verify that the source and target are synchronized. At a minimum, compare the document count for each source and target collection.

Register Microsoft.DataMigration resource provider in your subscription

To register the Microsoft.DataMigration resource provider in your subscription, follow these steps:

Azure portal

  1. Go to the Azure portal and navigate to your subscription.

  2. In the left-hand menu, select Resource providers under Settings.

  3. Search for Microsoft.DataMigration in the search box at the top.

  4. If it's not registered, select it and select the Register button.

Azure CLI

  1. Open the Azure Cloud Shell or your local terminal.

  2. Run the following command to register the resource provider:

    az provider register --namespace Microsoft.DataMigration

PowerShell

  1. Open the Azure Cloud Shell or your local PowerShell.

  2. Run the following command to register the resource provider:

    Register-AzResourceProvider -ProviderNamespace "Microsoft.DataMigration"

FAQ

Why are views missing in the select collection screen step when Azure DocumentDB supports views?

Azure DocumentDB supports the creation of new views. However, the DMS migration experience doesn't support migrating existing views.

After the migration finishes, you can always recreate the views.

Which collections and databases does the migration process skip when migrating from MongoDB to Azure DocumentDB?

The migration process considers the following databases and collections as internal for MongoDB:

Category Description
Databases admin, local, system config
Collections Any collection with prefix system.

Does the migration continue after I leave the Azure portal?

Yes. DMS executes the data migration in Azure and doesn't rely on your browser after you submit the job. You can close the Azure portal and return to the DMS resource later to monitor the job.

Can I rename databases and collections during migration?

The DMS migration experience doesn't support database and collection renaming during migration.

How should I configure my source server firewalls to avoid connectivity problems?

The required network configuration depends on the selected connectivity mode:

  • Public mode: Allow the IP addresses that the wizard displays on both the source and target firewalls to enable communication.
  • Private mode: Enable virtual network integration so that the DMS servers can securely communicate with the source and target endpoints within the virtual network.

For detailed validation steps and troubleshooting, see Troubleshoot connectivity.

How many databases and collections can I migrate in a single migration?

You can include unlimited collections in a single migration.

How many migration jobs can I run simultaneously?

You can run multiple migration jobs when using public access. However, when using private access, a single virtual network supports only one active job at a time. To run multiple jobs with private access, use different virtual networks for each job.

Related content

  • Last updated on