Azure Cosmos DB for MongoDB vCore migration extension for Azure Data Studio (preview)

The Azure Cosmos DB for MongoDB migration extension helps you in migrating your MongoDB workloads to Azure Cosmos DB. You can use this extension to:

• Run an end-to-end assessment on your workload and find out the necessary actions you need to take to migrate your workloads to Azure Cosmos DB for MongoDB vCore.
• Perform the migration operation with selected databases and collections to Azure Cosmos DB for MongoDB vCore.

Prerequisites

• An existing Azure Cosmos DB for MongoDB vCore account.
  • If you don't have an Azure subscription, create an account for free.
• Latest version of Azure Data Studio.
• MongoDB running version 3.2 or higher.

Prepare

Prior to starting the migration, carry out up-front planning and decision-making about your migration before you actually move any data.

• For more information about premigration planning for the API for MongoDB vCore, see premigration steps for Azure Cosmos DB for MongoDB vCore,
• For more information about premigration planning for the API for MongoDB RU, see premigration steps for Azure Cosmos DB for MongoDB RU

Install the extension

Install the Azure Cosmos DB for MongoDB migration extension in Azure Data Studio before you begin your migration.

1. Open the extensions manager in Azure Data Studio. Either select the extensions icon or select Extensions in the View menu.

2. Enter Cosmos in the search bar.

3. Select the Azure Cosmos DB Migration for MongoDB extension and view its details.

   

4. Select Install.

Configure extension settings

You can configure some extension settings after installing the extension. This step is optional. If no settings are explicitly configured, the extension uses default settings.

1. Go to extensions and select Azure Cosmos DB Migration for MongoDB, select the manage settings icon, and then select extension settings.

   

2. Under extension settings for this extension, provide the Assessment path to change the location where the assessment metadata is stored. If left blank, the default location is used.

Connect to the MongoDB source

Use the extension for the first time to connect to the existing MongoDB "source" instance. Ensure that you have the connection credentials for the source ready before starting this section.

1. Locate the connections icon in the menu bar, and select New Connection.

   

2. In the Connection pane, fill out the following fields:

   	Value
   Connection type	Azure Cosmos DB for MongoDB
   Connection string/Parameters	Use the connection string or parameters for your existing source MongoDB instance.
   Server group	Default
   Name (optional)	Provide a unique name for this connection.

3. Select Connect.

4. Open the context menu for the new connection in the Connections pane. Then, select Manage.

   

5. Select Azure Cosmos DB Migration.

   

Run an assessment

The assessment examines your current MongoDB data estate and utilization. The assessment feature then generates a comprehensive report that helps you identify the necessary actions to take before migrating your workloads to Azure Cosmos DB for MongoDB.

1. Locate and navigate to the Dashboard tab. Then, select Assess and Migrate Databases(s).

   

2. Complete the wizard to provide details to the extension so that it can perform an assessment.

   

   1. In the Assessment name field, enter a title.

   2. Select the target Azure Cosmos DB for MongoDB account from the Offering dropdown.

   3. Provide the path to MongoDB Logs.

      Tip

      This is an optional field, providing the logs path yields more detailed insights at the collection level. When the log folder isn’t specified, the tool relies on information from the serverStatus command for the assessment. Keep in mind that the 'serverStatus' command reports feature usage only since the last server restart. To obtain an assessment that accurately reflects your actual workload, ensure sufficient time has elapsed since the most recent server restart.

   4. Provide the path to Data assessment logs.

      Tip

      While this field remains optional, including data assessment logs can offer more comprehensive insights into the workload. These logs are acquired by scanning data and reviewing detailed logs. The data assessment independently executes as a command-line interface (CLI) before initiating the migration assessment, and the resulting JSON is subsequently provided here. Download the data assessment CLI here.

   5. Select Run validation to validate the assessment inputs.

3. Once the validation is successful, select Start assessment to run the assessment.

   

4. Depending on the size of your source server, the assessment takes a few minutes. Wait for the assessment to complete before continuing.

   

5. After the assessment is complete, you should now have an assessment report.

   

6. In the assessment report, select the instance name to review a list of server-wide issues. Select a specific database to view issues that are only applicable to the selected database.

   

7. Select Download Report to get a consolidated downloadable report.

8. Study the assessment report to identify any actions you need to take for a seamless migration of your workloads on Azure Cosmos DB for MongoDB. Before moving to the next step, ensure that all blocking issues reported in the assessment are handled. If there are any unresolved issues, you can exit the process and handle them later. Once the issues are resolved, you can come back and restart the assessment and migration process.

Perform an offline migration

Now, use the assessment report to perform an offline migration of your data from your source MongoDB instance to your target Azure Cosmos DB for MongoDB vCore account.

1. In the assessment report screen, select any databases you plan to migrate. Then, select Next.

   

2. Narrow down the lists to Select the target Azure Cosmos DB for MongoDB account by filtering by subscription and then resource group. Then provide any connection credentials necessary to connect to the account.

   

3. Select Test connection to validate the credentials for the Azure Cosmos DB for MongoDB account. Select Next to navigate to the mapping of collections from the source to the target.

   Important

   Currently the extension doesn't support Private Endpoint enabled source or target MongoDB instances.

   • Configure the source MongoDB instance to allow connections from global Azure datacenters.
   • Add firewall exceptions to the Azure Cosmos DB for MongoDB vCore target account to permit connections from global Azure datacenters.
   • To locate the relevant IP range information download JSON from global Azure IP address ranges and look for "AzureCloud.{Target Cosmos DB Account Region}" within the JSON file.

4. Choose either Skip or Migrate for each collection in the list of mappings. Collections that already exist in the target are automatically marked with an icon and set to Skip by default. Select Next to configure the Azure Database Migration Service (DMS).

   

   Warning

   Opting to Migrate an existing collection will overwrite the entire collection, resulting in irrecoverable data loss. Please exercise caution when choosing this option.

5. Choose an existing Azure Database Migration Service instance from the dropdown or select Create New to create a new migration service. Azure Database Migration Service is a service that migrates data to and from Azure data platforms by using cloud infrastructure for data transfer, instead of relying on local resources.

   

   Important

   If you're using Database Migration Service for the first time, make sure that the Microsoft.DataMigration resource provider is registered in your subscription.

6. Select Next to view the migration summary. Once you reviewed and confirmed the details, select Create Schema to create resources on the target account.

   

7. Select Start Migration to initiate the data transfer using the selected migration service.

   

8. View the migration status on the dashboard page once the jobs are initialized.

   

9. Select a specific migration from the list of migrations to view more details. Wait for the migration to complete before continuing.

   

   Note

   You don’t need to remain connected to the migration service or Azure Data Studio while the migration jobs are executed remotely and asynchronously. The migration jobs are executed on the migration service, and the status will be updated on the dashboard at frequent intervals.

   If you selected more than 50 collections to migrate, the migration job will be batched into multiple jobs on the migration service, each containing max of 50 collections.

10. Once the job is complete, the migration status indicates success.

    

View past migrations and assessments

It's often useful to review past assessments and migrations. The extension provides an interface to review summaries of past assessment and migrations. The extension also provides the capability to review detailed historical assessment reports.

1. To view past migrations, select the Migrations tab in the toolbar. The migrations list contains all migrations that were initiated on the current machine. You can select on a specific migration in the list to get more details.

   

2. To view past assessments, select the Assessments tab in the toolbar. The assessments list contains all assessments that were initiated on the current machine.

   

Next step