You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Migrate Data Using the Desktop Data Migration Tool
3
-
description: Use the desktop data migration tool to migrate data from JSON, MongoDB, SQL Server, or Azure Table storage to Azure Cosmos DB.
2
+
title: Migrate Data Using the Data Migration Tool
3
+
description: Use the Azure Cosmos DB Data Migration Tool to migrate data from JSON, MongoDB, SQL Server, and many other databases and file formats to Azure Cosmos DB.
4
4
author: sandeepsnairms
5
5
ms.author: sandnair
6
6
ms.service: azure-cosmos-db
7
7
ms.subservice: nosql
8
8
ms.topic: how-to
9
-
ms.date: 06/26/2025
9
+
ms.date: 01/20/2026
10
10
ms.custom: sfi-ropc-blocked
11
11
# CustomerIntent: As a database owner, I want to use a tool to perform migration to Azure Cosmos DB so that I can streamline large and complex migrations.
12
12
appliesto:
@@ -15,244 +15,171 @@ appliesto:
15
15
- ✅ Table
16
16
---
17
17
18
-
# Migrate data using the desktop data migration tool
18
+
# Migrate data using the Data Migration Tool
19
19
20
-
The [Azure Cosmos DB desktop data migration tool](https://github.com/azurecosmosdb/data-migration-desktop-tool) is an open-source command-line application to import or export data from Azure Cosmos DB. The tool can migrate data to and from many sources and sinks including, but not limited to:
20
+
The [Azure Cosmos DB Data Migration Tool](https://github.com/azurecosmosdb/data-migration-desktop-tool) is an open-source command-line application to import or export data from Azure Cosmos DB. The tool is built on an extension model for source and sink objects to migrate data.
21
21
22
-
- Azure Cosmos DB for NoSQL
23
-
- Azure Cosmos DB for MongoDB
24
-
- Azure Cosmos DB for Table
25
-
- Azure Table storage
26
-
- JSON
27
-
- MongoDB
28
-
- SQL Server
22
+
## Supported extensions
29
23
30
-
> [!IMPORTANT]
31
-
> For this guide, you perform a data migration from JSON to Azure Cosmos DB for NoSQL.
24
+
-[Azure Cosmos DB for NoSQL](https://github.com/AzureCosmosDB/data-migration-desktop-tool/blob/main/Extensions/Cosmos/README.md)
-[Azure AI Search (Cognitive Search)](https://github.com/AzureCosmosDB/data-migration-desktop-tool/blob/main/Extensions/CognitiveSearch/README.md)
34
+
-[Azure Cosmos DB for Table](https://github.com/AzureCosmosDB/data-migration-desktop-tool/blob/main/Extensions/AzureTableAPI/README.md)
32
35
33
36
## Prerequisites
34
37
35
38
- An existing Azure Cosmos DB for NoSQL account.
36
39
- If you have an Azure subscription, [create a new account](how-to-create-account.md?tabs=azure-portal).
37
40
- If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn) before you begin.
38
-
-Latest version of [Azure CLI](/cli/azure/install-azure-cli).
39
-
-[.NET 6.0](https://dotnet.microsoft.com/download/dotnet/6.0) or later.
41
+
-[.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) or later on your local machine.
First, install the latest version of the desktop data migration tool from the GitHub repository.
46
+
The easiest way to use the container is to pull the prebuilt image from Microsoft Container Registry. [Docker Desktop](https://docs.docker.com/get-started/get-docker/) is required.
44
47
45
48
> [!NOTE]
46
-
> The desktop data migration tool requires [.NET 6.0](https://dotnet.microsoft.com/download/dotnet/6.0) or later on your local machine.
49
+
> The Data Migration Tool can also be configured to run in any containerized environment or as part of a GitHub Action. See [Run in a Docker Container](https://github.com/AzureCosmosDB/data-migration-desktop-tool?tab=readme-ov-file#docker-container) for more details.
47
50
48
-
1. In your browser, navigate to the [**Releases** section of the repository](https://github.com/azurecosmosdb/data-migration-desktop-tool/releases).
49
-
50
-
1. Download the latest compressed folder for your platform. There are compressed folders for the **win-x64**, **mac-x64**, and **linux-x64** platforms.
51
-
52
-
1. Extract the files to an install location on your local machine.
53
-
54
-
1. (Optional) Add the desktop data migration tool to the `PATH` environment variable of your local machine.
51
+
1. Pull the latest version of the container from the registry.
Next, create a target database and container on the Azure Cosmos DB for NoSQL account.
57
+
1. Configure the migration settings. See [Configure migration settings](#configure-migration-settings)
59
58
60
-
### [Azure CLI](#tab/azure-cli)
59
+
```shell
60
+
docker run -v $(pwd)/config:/config -v $(pwd)/data:/data mcr.microsoft.com/azurecosmosdb/linux/azure-cosmos-dmt:latest run --settings /config/migrationsettings.json
61
+
```
61
62
62
-
1. Open a new terminal. If you haven't already, [sign in to the Azure CLI](/cli/azure/authenticate-azure-cli).
63
+
## Using from command line
63
64
64
-
1.Create new shell variables for the Azure Cosmos DB account's name and resource group.
65
+
1.In your browser, navigate to the [**Releases** section of the repository](https://github.com/azurecosmosdb/data-migration-desktop-tool/releases).
1. Download the latest compressed folder for your platform. There are compressed folders for win-x64, win-arm64, mac-x64, mac-arm64, linux-x64, and linux-arm64 platforms.
73
68
74
-
1. Create a new database using [`az cosmosdb sql database create`](/cli/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create). Name the new database `cosmicworks` and configure the database with 400 RU/s of shared throughput.
69
+
1.Extract the files to an install location on your local machine.
75
70
76
-
```azurecli-interactive
77
-
az cosmosdb sql database create \
78
-
--resource-group $resourceGroupName \
79
-
--account-name $accountName \
80
-
--name cosmicworks \
81
-
--throughput 400
82
-
```
71
+
1. (Optional) Add the Data Migration Tool to the `PATH` environment variable of your local machine.
83
72
84
-
1. Use [`az cosmosdb sql container create`](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create) to create a new container named `products` within the `cosmicworks` database. Set the partition key path of the new container to `/category`.
73
+
1.Configure the migration settings. See [Configure migration settings](#configure-migration-settings)
85
74
86
-
```azurecli-interactive
87
-
az cosmosdb sql container create \
88
-
--resource-group $resourceGroupName \
89
-
--account-name $accountName \
90
-
--database-name cosmicworks \
91
-
--name products \
92
-
--partition-key-path "/category"
93
-
```
75
+
1. Run the Data Migration Tool using the `dmt` command from a terminal.
94
76
95
-
1. Find the *primary connection string* from the list of keys for the account with [`az cosmosdb keys list`](/cli/azure/cosmosdb/keys#az-cosmosdb-keys-list).
96
-
97
-
```azurecli-interactive
98
-
az cosmosdb keys list \
99
-
--resource-group $resourceGroupName \
100
-
--name $accountName \
101
-
--type connection-strings
77
+
```terminal
78
+
dmt
102
79
```
103
80
104
-
1. Record the *primary connection string* value. You use this credential later when migrating data with the tool.
105
-
106
-
### [Azure PowerShell](#tab/azure-powershell)
107
-
108
-
1. Open a new terminal. If you haven't already, [sign in to the Azure CLI](/cli/azure/authenticate-azure-cli).
109
-
110
-
1. Create new variables for the Azure Cosmos DB account's name and resource group.
> If you didn't add the installation path to your `PATH` environment variable, you might need to specify the full path to the `dmt` executable.
119
83
120
-
1. Create a new database using [`New-AzCosmosDBSqlDatabase`](/powershell/module/az.cosmosdb/new-azcosmosdbsqldatabase). Name the new database `cosmicworks` and configure the database with 400 RU/s of shared throughput.
84
+
1. The tool outputs the sources and sinks used by the migration.
121
85
122
-
```azurepowershell-interactive
123
-
$parameters = @{
124
-
ResourceGroupName = $RESOURCE_GROUP_NAME
125
-
AccountName = $ACCOUNT_NAME
126
-
Name = "cosmicworks"
127
-
Throughput = 400
128
-
}
129
-
New-AzCosmosDBSqlDatabase @parameters
86
+
```output
87
+
Using JSON Source
88
+
Using Cosmos-nosql Sink
130
89
```
131
90
132
-
1. Use [`New-AzCosmosDBSqlContainer`](/powershell/module/az.cosmosdb/new-azcosmosdbsqlcontainer) to create a new container named `products` within the `cosmicworks` database. Set the partition key path of the new container to `/category`.
91
+
## Configure migration settings
133
92
134
-
```azurepowershell-interactive
135
-
$parameters = @{
136
-
ResourceGroupName = $RESOURCE_GROUP_NAME
137
-
AccountName = $ACCOUNT_NAME
138
-
DatabaseName = "cosmicworks"
139
-
Name = "products"
140
-
PartitionKeyPath = "/category"
141
-
PartitionKeyKind = "Hash"
142
-
}
143
-
New-AzCosmosDBSqlContainer @parameters
144
-
```
93
+
The Data Migration Tool uses a migrationsettings.json to define the source and sink settings for the data to be copied. See [Supported Extension](#supported-extensions) for details on each extensions migration settings.
145
94
146
-
1. Find the *primary connection string* from the list of keys for the account with [`Get-AzCosmosDBAccountKey`](/powershell/module/az.cosmosdb/get-azcosmosdbaccountkey).
95
+
Here's an example for migrating a [sample JSON file](https://github.com/AzureCosmosDB/data-migration-desktop-tool/blob/main/data/sample-data.json) to the Cosmos DB emulator.
1. Record the *primary connection string* value. You use this credential later when migrating data with the tool.
112
+
}
113
+
```
158
114
159
-
---
160
-
161
-
## Perform a migration operation
162
-
163
-
Now, migrate data from a JSON array to the newly created Azure Cosmos DB for NoSQL container.
115
+
### Migrate multiple sources
164
116
165
-
1. Navigate to an empty directory on your local machine. Within that directory, create a new file named *migrationsettings.json*.
117
+
The migrationsettings.json can also be configured to execute multiple data transfer operations with a single run command with an *Operations* property consisting of an array of objects that include SourceSettings and SinkSettings for the extensions referenced in the *Source* and *Sink* properties.
166
118
167
-
1. Within the JSON file, create a new empty JSON object:
168
-
169
-
```json
170
-
{}
171
-
```
119
+
Here's an example:
172
120
173
-
1. Create a new property named `Source` with the value `json`. Create another new property named `SourceSettings` with an empty object as the value.
1. Within the `SourceSettings` object, create a new property named `FilePath` with the value set to this URI: [https://raw.githubusercontent.com/azure-samples/cosmos-db-migration-sample-data/main/nosql-data.json](https://github.com/azure-samples/cosmos-db-migration-sample-data/blob/main/nosql-data.json).
1. Within `SinkSettings`, create a property named `ConnectionString` with the *primary connection string* you recorded earlier in this guide as its value.
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments