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 why and how to move MongoDB clusters that you host yourself, on Azure virtual machines, on another cloud's virtual machines, or on servers on-premises, to Azure DocumentDB (with MongoDB compatibility). Azure DocumentDB is a fully managed, MongoDB-compatible database on Azure. When you migrate, Azure takes over the virtual machines, disks, replication, security infrastructure, and fleet operations that your team runs today. Your applications keep using their existing MongoDB drivers, tools, and queries, and Azure DocumentDB supports 99.03% of MongoDB operators. You can migrate online, with minimal downtime, using the migration tools provided and supported by Azure DocumentDB.
For the general migration process and the full list of tools, see Migration options.
Summary
| Migration scenario | Notes |
|---|---|
| Migration path | Self-hosted MongoDB (Azure VMs, other cloud VMs, or on-premises) → Azure DocumentDB |
| What you stop managing | Compute nodes for the cluster and their uptime, high availability for the cluster, storage disks, their IOPS and bandwidth, node-to-node replication, networking, elasticity, security infrastructure, patching, upgrades, backups, and fleet operations |
| Application code changes | Usually none beyond the connection string |
| Recommended tool | Azure DocumentDB migration extension for Visual Studio Code |
| Migration type | Online, using change streams, with minimal downtime |
| Availability | Comprehensive availability SLA covering the database, infrastructure, and networking |
| Test environment | Free tier: 32 GB of storage |
What you no longer manage
When you run MongoDB yourself, you run every layer under it. By using Azure DocumentDB, Azure runs and manages those layers for you. Your team works only with databases, collections, indexes, and queries. You can devote your time and your agent's time entirely to experimenting, iterating, and scaling solutions.
| Area | What you manage when self-hosting | What Azure DocumentDB does for you |
|---|---|---|
| Virtual machines | Sizing, provisioning, OS images, OS patching, VM health, replacing failed VMs | Provisions and operates the compute for each shard. You only choose a cluster tier and Azure DocumentDB manages the rest. |
| High availability | Replica set members across zones, arbiters, elections, failover testing | A standby replica for each shard in another availability zone (for Azure regions that support zones), with automatic failover |
| Sidecar processes | Backup agents, monitoring and log-shipping agents, and process supervisors on every VM | None. Backups, metrics, and logs are built in. |
| Disks | Disk type and size, IOPS and throughput settings, striping, resizing, monitoring disk health and latency | Premium SSD v2 storage, with the highest IOPS and disk bandwidth included. You only choose the storage size and Azure DocumentDB manages the rest. |
| Replication networking | Network paths between members, TLS and internal authentication (keyfiles or x.509), cross-zone and cross-region traffic | Secure replication between nodes, fully managed for you by Azure DocumentDB |
| Network security | Firewall rules, private connectivity, certificates | Firewall rules, Azure Private Link, and private endpoints, configured on the cluster and fully managed by Azure DocumentDB |
| Identity and access | Database users and roles on every cluster, credential rotation | Microsoft Entra ID, built-in and custom database and collection level roles, managed identities |
| Backups | Backup scripts or tools, schedules, storage, retention, restore testing | Automatic backups for up to 35 days with point-in-time restore, included for all production SKUs (M30 and above) |
| Upgrades | Planning and running MongoDB version upgrades on each cluster | Versioning and cluster upgrades, including security and OS patches, are fully managed by Azure DocumentDB |
| Scaling | Resizing VMs, adding disks, adding shards and rebalancing | Change the compute cluster tier and increase storage as needed. Azure DocumentDB sees the scaling operations through to completion while guaranteeing full uptime |
| Monitoring | Running a monitoring stack, dashboards, alerts | Azure Monitor metrics, diagnostic logs, and custom alerting capabilities |
| Fleet operations | Keeping many clusters consistent in configuration, versions, and security | Azure Resource Manager and tags for easy management and visibility |
The sections in the following list explain each area in more detail.
Virtual machines and uptime
A self-hosted replica set needs multiple healthy virtual machines, spread across availability zones, plus the operating system patching, monitoring, and replacement work to keep them healthy. Each VM often runs sidecar processes, such as backup agents, log shippers, and monitoring agents, that also need to stay up.
With Azure DocumentDB, you don't create or manage virtual machines. You choose a compute cluster tier, the compute size for each shard, and Azure DocumentDB:
- Runs a standby replica for each shard in another availability zone (for all Azure regions that support availability zones) when you turn on high availability, and fails over automatically.
- Monitors node health and replaces unhealthy nodes without your involvement.
- Patches the operating system and database engine.
- Backs up and monitors the cluster without any agents on your side.
Highly available clusters are covered by a comprehensive availability SLA that includes the database engine, Azure infrastructure, storage, and networking.
Disks and storage performance
On virtual machines, database performance often depends on disk configuration: choosing disk types, provisioning IOPS and disk bandwidth, striping disks for larger volumes, and watching disk latency and capacity on every node.
With Azure DocumentDB, you choose only a storage size for each shard:
- Premium SSD v2 storage, which also provides the maximum configurable IOPS (80,000) and disk bandwidth (1.2 GiB/s).
- Storage scales separately from compute, so you add storage without resizing compute.
- Up to 32 TB of storage per node, so most workloads don't need sharding until they reach multiple terabytes.
You don't monitor individual disks or tune IOPS and throughput per volume.
Networking and secure replication
A replica set or sharded cluster on virtual machines needs a secure network between its members - routing between zones or regions, TLS certificates, internal authentication with keyfiles or x.509 certificates, and firewall rules that allow replication traffic but nothing else.
With Azure DocumentDB, replication between nodes is configured, encrypted, and maintained by the service. You manage only how your applications reach the cluster. For data in other regions, add cross-region replicas instead of building your own replication network.
Security
Self-hosted security spans several layers that you configure and keep consistent on every cluster. With Azure DocumentDB, each layer is a setting on the cluster:
- Network access: firewall rules on the cluster's public endpoint, or Azure Private Link with private endpoints in your virtual networks. See Use Azure Private Link and Manage public access.
- Identity: Microsoft Entra ID authentication alongside native database users, plus managed identities for service-to-service access. See Microsoft Entra ID authentication.
- Authorization: built-in roles and fine-grained role-based access control at a database and collection level.
- Encryption: data encrypted at rest and in transit by default, with optional customer-managed keys in Azure Key Vault. See Encryption at rest.
- Posture: Microsoft is responsible for the security and compliance posture of the service. See Security best practices.
Managing a fleet
Many teams run not just one MongoDB deployment but several - one per application, environment, or customer. Every self-hosted cluster multiplies the work above and makes it harder to keep versions, settings, and security consistent.
By using Azure DocumentDB, you can manage every cluster as an Azure resource, so you can manage a fleet the same way you manage the rest of Azure:
- Create clusters consistently with Bicep, ARM templates, the Azure CLI, or Terraform.
- Enforce standards for example requiring private endpoints or Microsoft Entra ID.
- Monitor every cluster in one place with Azure Monitor and Azure Log Analytics.
- Track cost per application, team, or environment with tags and Microsoft Cost Management, on one Azure bill.
Signs that this migration fits your needs
You're likely to benefit from migrating if your self-hosted MongoDB environment includes any of these features:
- Infrastructure code for MongoDB virtual machines, such as Terraform, Bicep, Ansible, or scripts that create VMs, attach disks, or configure
mongod. - Custom backup jobs, such as scheduled
mongodumpscripts or backup agents. - Replica set or sharding configuration that you maintain, such as keyfiles, certificates,
rs.initiate()scripts, or config server setup. - Runbooks for failover, patching, or version upgrades.
- A monitoring stack built for MongoDB, such as exporters and dashboards for each node.
- Many small clusters, one per application, customer, or environment, that each need the same care.
Before you start
Assess compatibility
Run the compatibility assessment in the Azure DocumentDB migration extension for Visual Studio Code against your source deployment. It reports unsupported features, commands, query syntax, and index types. See Assess and plan migration readiness.
Check your source for online migration
Online migration reads changes through change streams, which need a replica set.
- Replica sets: supported. Ensure the oplog is large enough to cover the whole migration window, including the initial copy of your largest collections.
- Standalone
mongodservers: they don't have an oplog. Convert the server to a single-member replica set before migrating, or use an offline migration with native MongoDB tools. - Sharded clusters: follow the same migration path as unsharded clusters after determining whether collections will remain unsharded, if large collections will be sharded while smaller collections will remain unsharded, or if you use a mix of sharded and unsharded collections.
Create a database user for the migration
Create a dedicated user on the source with read access to every database or collection you're migrating and permission to read change streams. Remove it after cutover.
Size your cluster from your current VMs
Use your current deployment as a starting point, then confirm with a trial migration.
| Your current deployment | Azure DocumentDB setting |
|---|---|
| vCPUs and memory of each data-bearing VM | Azure DocumentDB Compute Cluster tier |
| Data plus index size on each node, with room to grow | Storage per shard |
| Replica set members across zones | High availability enabled |
| Number of shards | Shard count. You might need fewer on Azure DocumentDB, because a physical shard supports up to 32 TB. |
| Secondaries in other regions | Cross-region replicas |
| Separate dev and test deployments | Non-production clusters tiers (M10, M20 and M25) without high availability, or the free tier |
Set up network access
| Where your source runs | How the migration tool reaches it |
|---|---|
| Azure virtual machines | Run the migration tool in the same or a peered virtual network. |
| On-premises servers | Connect through a site-to-site VPN or Azure ExpressRoute to an Azure virtual network, or run the migration tool on a machine on-premises with outbound access to Azure. |
| Another cloud's virtual machines | Run the migration tool inside that network with outbound access to Azure, or connect the networks with a site-to-site VPN. |
Create your Azure DocumentDB cluster in the region where your application will run after cutover. For on-premises and other-cloud sources, your provider might charge for data leaving its network during migration.
Migrate
- Create a test cluster. Create the Azure DocumentDB cluster, and run your application's integration tests against it.
- Run a trial migration on a representative subset of data to confirm throughput, cluster tier, storage, and shard count.
- Create your production cluster with the preferred Compute cluster tier and storage size to account for storage and throughput growth.
- Run an online migration with the migration extension or Azure Database Migration Service.
- Wait until replication lag is consistently low and then cutover to the Azure DocumentDB cluster.
Update your application
- Replace the connection string with your Azure DocumentDB cluster's connection string. Store it in configuration or Azure Key Vault.
- Remove self-hosted settings, such as replica set member host lists,
replicaSetnames, and paths to your own CA certificates. - Keep your driver. Your existing MongoDB driver works. Upgrading to a current version is recommended.
- Optionally, use Microsoft Entra ID for authentication.
Cut over
- Validate the data. Compare document counts per collection, check a sample of documents, and confirm that they exist on the target.
- Move read traffic first, and confirm results and performance.
- Stop writes to the source during a short maintenance window and ideally during periods of lowest traffic.
- Let the last changes replicate, then stop the migration job.
- Move write traffic by switching to the new Azure DocumentDB connection string.
- Monitor with Azure Monitor metrics during the first hours after cutover.
Keep your source servers running, unchanged, until you're confident in the migration. Once the target Azure DocumentDB has been fully validated post-migration, and production workloads are running as expected, the source servers can be decommissioned.
Decommission the old environment
After cutover, retire what you no longer need:
- Self-hosted IaaS virtual machines, disks, and snapshots
- Backup jobs, backup storage, and agents
- Monitoring exporters, dashboards, and alerts for the old nodes
- Replication network rules, keyfiles, and certificates
- Infrastructure code and runbooks for the old deployment
- The migration database user on the source
Frequently asked questions
Do I need to change my application?
Usually, you only need to change the connection string while the application code remains as is. Azure DocumentDB uses the MongoDB wire protocol, so your driver and queries keep working. Run the compatibility assessment to confirm for your workload.
Can I keep some workloads on-premises?
Yes. Azure DocumentDB is built on the open-source DocumentDB engine, which you can run on-premises with the DocumentDB Kubernetes operator. Applications use the same drivers and interface in both places, and Azure DocumentDB supports cross-cloud replication and failover with self-hosted DocumentDB.
Does MongoDB's SSPL license apply to Azure DocumentDB?
No. Azure DocumentDB doesn't run the MongoDB server or its codebase. It's built on the open-source DocumentDB engine, released under the MIT license.
How much downtime does migration need?
The migration itself doesn't incur any downtime. The cutover after a migration typically only requires time to stop writes, let the last changes replicate, and switch your connection string. You can do this work within a short maintenance window. You can minimize downtime by scheduling the maintenance window during the lowest traffic period of the day or month.