Announcing the New Azure Cosmos DB Desktop Data Migration Tool

Mark Brown

Today we’re excited to introduce a brand new Azure Cosmos DB Desktop Data Migration Tool. You can find the new tool at Read more about it below and how to use it.


Some History

The old Data Migration Tool (or DMT as it was known) was originally created in 2015 and had become outdated. It was built on the Microsoft .NET framework 4.5.1, which meant that it was Windows only and also made it difficult to upgrade to modern versions of .NET. It also used the original DocumentDB client for .NET which has since been replaced by the newer Microsoft.Azure.Cosmos client library and uses a completely different architecture. Using the old library meant that as new features have been added to the Azure Cosmos DB platform, and then supported in the new client library, there was no path to add that same support to the migration tool. Besides being somewhat orphaned from any new features in Cosmos DB, the performance of the old DocumentDB libraries was nowhere near as good as they were with the new Cosmos client.


The New Version

A team at Solliance, who were frequent users of the old tool, approached our team and asked if we were ever going to update this old tool. They also indicated that, if we were ok with it, they would be willing to update this tool, designing and building a completely new version from scratch. The tool was already an open project with an open source license

The new tool is built on .NET 6 and designed to be cross platform. Like the old tool, it uses a plugin architecture to make it extensible for adding support for new data stores. The initial release includes a cross-platform console application and the five initial plugin extensions, all of which include both source and sink implementations for exporting or importing data for these database API’s and formats:

  1. Cosmos DB NoSql
  2. JSON
  3. MongoDB
  4. Azure Table API
  5. SQL Server

Using the Tool

Settings can be provided to the tool in different ways including command line parameters and environment variables but the easiest way to get started is by creating a file named migrationsettings.json. The individual settings used for each extension vary and can be found in documentation for each extension. This example uses the JSON extension as source and Cosmos-NoSql extension as sink.

    "Source": "json",
    "Sink": "cosmos-nosql",
    "SourceSettings": {
    "FilePath": "my-data.json"
"SinkSettings": {
    "ConnectionString": "AccountEndpoint=...",
    "Database": "myDb",
    "Container": "myContainer",
    "PartitionKeyPath": "/id",
    "RecreateContainer": true

Once the migrationsettings file has been created, all that’s needed is to run dmt.exe from the folder where your file is located. For example, if I install the app in c:\apps\dmt and save my migrationsettings.json file in c:\data-transfer I would run this in PowerShell:

Image dmtps

Other Settings

By choosing a different source I also change which settings are available. This example reads data from MongoDB and uses some of the additional options settings for Cosmos-NoSql to change the data transfer behavior and allow updating existing container items:

    "Source": "mongo",
    "Sink": "cosmos-nosql",
    "SourceSettings": {
        "ConnectionString": "mongodb://...",
        "DatabaseName": "myDb",
        "Collection": "myCollection"
"SinkSettings": {
    "ConnectionString": "AccountEndpoint=...",
    "Database": "myDb",
    "Container": "myContainer",
    "PartitionKeyPath": "/id",
    "ConnectionMode": "Direct",
    "MaxRetryCount": 10,
    "WriteMode": "Upsert"

I can also use a different file name or place the file elsewhere in my file system and then use the –settings parameter to specify the file’s path: c:\apps\dmt\dmt.exe –settings c:\settings\mongo-cosmos-nosql-settings.json

To see all of the available commands and options the app supports look at the in-app help (dmt.exe -h)



Image dmt h


Get Started

Thanks to the open-source project and the plugin model we welcome you to add additional data stores that you would like to use with the tool. The steps for creating new plugin extensions can be found in the developer documentation and any additions you make can be contributed back to the main project!

Or visit the GitHub project to find the code and documentation and provide feedback or suggest new features. We’re looking forward to hearing from you!


Discussion is closed. Login to edit/delete existing comments.

  • Natalia Brett 0

    Thank you for publishing this project.
    I’m not a developer but need to export data FROM Cosmos DB into JSON (csv) file.
    Can your application do it?
    What should I change in the configuration/settings?

    Thank you,
    Natalia Brett

    • Mark BrownMicrosoft employee 0

      JSON and CSV are different formats.

      The tool supports JSON. It doesn’t support CSV. CSV must be tabular data. Document databases support hierarchical data which is incompatible with CSV format.

      That said, if your data is completely tabular, you could export the data as JSON and then use another utility to convert that into CSV.

  • Paulo Pinto 0

    While the tool is appreciated, what happend to the old Microsoft that used to create nice graphical tooling for developers?

    Just because UNIX won the server room, doesn’t mean the desktop developer experience has to be reduced to the terminal.

    • Mark BrownMicrosoft employee 0

      Microsoft didn’t create this. It was created by a group of community members in their spare time over a period of well over a year, working during off-hours when they could.

      Building a UX initially was something these community members did consider. However, they felt that it was best to share what they had built now, since it its core and extensibility model was functionally complete and the most popular extensions available. Users who really needed this tool could get their hands on it now and use it.

      So while it doesn’t have a graphical UX now, it could if one or more community members want to start work contributing to it.

Feedback usabilla icon