Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article explains when migrating an application from Amazon DocumentDB to Azure DocumentDB (with MongoDB compatibility) is a good fit, and how to do it. Azure DocumentDB is a fully managed, MongoDB-compatible database on Azure that supports 99.03% of MongoDB operators. Azure DocumentDB requires users to only decide on the required compute cluster tier and storage (with the highest configured IOPS and disk bandwidth available by default). Azure DocumentDB runs on an open-source engine that can also run on-premises or on any cloud. You can migrate online, with minimal downtime, using tools provided and supported by the Azure DocumentDB team.
Note
Azure DocumentDB is a Microsoft Azure service. It isn't related to Amazon DocumentDB, a separate service offered by Amazon Web Services. The two services share part of a name but don't share an engine, a codebase, or an owner.
For the general migration process and the full list of tools, see Migration options.
Summary
| Migration Step | Notes |
|---|---|
| Application code changes | Usually none beyond the connection string. Drivers, tools, and MongoDB queries keep working. |
| Recommended tool | Azure DocumentDB migration extension for Visual Studio Code |
| Migration type | Online, using change streams, with minimal downtime |
| Compatibility check | Built into the migration extension |
| Test environment | Free tier: 32 GB of storage |
| Typical steps | Assess → enable change streams → set up network access → migrate online → validate → cut over |
When migrating to Azure DocumentDB fits
Migrating to Azure DocumentDB is a good fit when one or more of these conditions is true for your application.
You want to use the full MongoDB query language
Azure DocumentDB supports 99.03% of MongoDB operators: all 181 aggregation operators, 58 of 60 aggregation stages, 44 of 45 query and projection operators, and all 22 update operators. That support includes window functions with $setWindowFields, time-series gap filling with $densify and $fill, and combining collections with $unionWith. See MongoDB compatibility.
Signals in your code: you write workarounds in application code for aggregation stages or operators that your current database doesn't run, you want to adopt MongoDB features from newer MongoDB versions, or you're adding analytics and reporting queries to an operational application.
You don't want to make decisions that change with read and write volume
Azure DocumentDB requires you to make provisioning and scaling decisions based on only two factors - the compute cores for the cluster you choose and the storage you provision. The service includes embedded components for backups, Premium SSD v2 storage (with the maximum configurable IOPS and disk bandwidth), and text and vector search. See Azure DocumentDB pricing explained.
Signals: your database bill changes month to month with traffic, or you size and plan around I/O volume.
You want the same database everywhere you run
Azure DocumentDB is built on DocumentDB, an open-source engine released under the MIT license and governed by the Linux Foundation. You can run the same engine:
- On a laptop, for local development and offline tests.
- On-premises or on any cloud, with the DocumentDB Kubernetes operator.
- As a managed service on Azure, with Azure DocumentDB, including cross-cloud replication and failover with self-hosted DocumentDB.
Signals: you need a hybrid or multicloud architecture, you have data residency requirements in environments outside one cloud, or you want local development to match production.
You're building with AI agents or need fast, frequent environments
- Clusters provision in about a minute or two on the M10, M20, M25, and M30 tiers, with no opt-in.
- Free tier clusters provision in seconds and include 32 GB of storage. See Free tier.
- Vector search is built in, so retrieval-augmented generation (RAG) and agent memory can use the same database as your operational data. See Vector search.
Signals: agents or CI/CD pipelines create short-lived databases to test changes, or you're adding vector search to an existing application.
Your applications run on Azure, or are moving there
Azure DocumentDB is a first-party Azure service with Microsoft Entra ID authentication, Azure Private Link, customer-managed keys in Azure Key Vault, Azure Monitor, and a comprehensive availability SLA.
When to wait
Migration might not be the right next step if:
- Your application and its other dependencies must stay in another cloud for latency or data-residency reasons, and you don't plan to move them. You can still run the open-source DocumentDB engine in that environment.
- The compatibility assessment reports features your application depends on that Azure DocumentDB doesn't support, and you can't change that part of the application.
- You can't schedule a cutover window, even a short one, for switching your application's connection string.
Before you start
Assess compatibility
Run the compatibility assessment in the Azure DocumentDB migration extension for Visual Studio Code against your source cluster. It reports unsupported features, commands, query syntax, and index types. Resolve any findings before you migrate. See Assess and plan migration readiness.
Enable change streams on the source
Online migration reads changes from the source through change streams. On your Amazon DocumentDB source:
- Enable change streams for the databases and collections you're migrating.
- Set the change stream log retention long enough to cover the whole migration window, including the initial copy of your largest collections.
See the source service's documentation for the commands and parameters.
If you can't enable change streams, use an offline migration with mongodump and mongorestore. See Migrate using native MongoDB tools.
Create a database user for the migration
Create a dedicated user on the source cluster with read access to every database you're migrating and permission to read change streams. Remove the user after cutover.
Prepare the connection to the source
- TLS: the source typically requires TLS with the provider's certificate authority bundle. Make the bundle available to the migration tool.
- Connection string options: keep source-specific options, such as
retryWrites=false, only in the source connection string. Don't copy them into your application's Azure DocumentDB connection string.
Set up network access
Source clusters usually run inside a private virtual network on the source cloud and aren't reachable from the internet. Choose one way for the migration tool to reach the source:
| Option | When to use it |
|---|---|
| Run the migration tool on a virtual machine inside the source network, with outbound access to Azure | Simplest for most migrations |
| Connect the source network and an Azure virtual network with a site-to-site VPN | Larger migrations, or when you want private connectivity end to end |
| An SSH tunnel through a jump host in the source network | Small migrations and trials |
To keep the migration fast:
- Create your Azure DocumentDB cluster in the Azure region closest to the source region, or in the region where your application will run after cutover.
- Plan for data transfer charges. The source cloud provider might charge for data that leaves its network during the initial copy and replication.
Migrate
- Create a test cluster. Use a free tier cluster, or an M10–M30 cluster, which provisions in about a minute or two. Point your application's integration tests at it.
- Run a trial migration on a representative subset of data to measure throughput and confirm your cluster tier, storage, and shard count.
- Create your production cluster sized to your workload.
- Run an online migration with the migration extension or Azure Database Migration Service.
- Wait until replication lag is consistently low, so the target is nearly in sync with the source.
Update your application
In most applications, the only code change is the connection string.
- Replace the connection string with your Azure DocumentDB cluster's connection string from the Azure portal or the Azure CLI. Store it in your configuration or a secret store, such as Azure Key Vault.
- Remove source-specific options, such as
retryWrites=falseand paths to the source provider's certificate bundle. - Keep your driver. Your existing MongoDB driver works. Upgrading to a current driver version is recommended but not required.
- Simplify workarounds. If you added application code to work around aggregation stages or operators, you can move that logic back into the query.
- Optionally, use Microsoft Entra ID for authentication instead of a username and password. See Microsoft Entra ID authentication.
Cut over
- Validate the data. Compare document counts per collection, check a sample of documents, and confirm that indexes exist on the target.
- Move read traffic first, and confirm results and performance.
- Stop writes to the source during a short maintenance window.
- Let the last changes replicate, then stop the migration job.
- Move write traffic by deploying the new connection string.
- Monitor with Azure Monitor metrics during the first hours after cutover.
Keep the source cluster running, unchanged, until you're confident in the migration. Before new writes reach Azure DocumentDB, you can roll back by switching the connection string back. After that, rolling back requires migrating new writes back to the source, so decide your rollback point in advance.
Migration checklist
- Run compatibility assessment and resolve findings.
- Enable change streams on the source, with enough log retention.
- Create a migration user on the source.
- Test the network path from the migration tool to the source.
- Create a test cluster and pass integration tests.
- Complete a trial migration and size the target.
- Run online migration with low replication lag.
- Update the application connection string and remove source-specific options.
- Validate data.
- Complete cutover and decommission the source.
Frequently asked questions
Do I need to rewrite my application?
Usually not. Azure DocumentDB uses the MongoDB wire protocol, so your MongoDB driver and queries keep working. The required change is the connection string. Run the compatibility assessment to confirm for your workload.
Is Azure DocumentDB the same as Amazon DocumentDB?
No. They're separate services from different companies, built on different engines. Azure DocumentDB is built on the open-source DocumentDB engine governed by the Linux Foundation.
How much downtime does migration need?
With an online migration, you only need downtime for the time it takes to stop writes, let the last changes replicate, and switch your connection string. This downtime is typically a short maintenance window.
Can I try Azure DocumentDB before I migrate?
Yes. Create a free tier cluster with 32 GB of storage at no cost and with no expiry, and run your integration tests against it.
Which MongoDB versions does Azure DocumentDB support?
Azure DocumentDB supports MongoDB wire protocol versions 5.0, 6.0, 7.0, and 8.0.