Graceful Failovers in Azure DocumentDB – Now Generally Available

We are excited to announce the general availability of graceful failovers in Azure DocumentDB.

Not every region switch is because of availability loss. Whether you’re migrating your primary workload to a different Azure region or proactively moving ahead of a forecasted application-level upgrade, you need a failover mechanism that prioritizes data integrity over speed. One that lets you move deliberately, not reactively.

With Graceful Failover, you initiate a controlled promotion of your replica cluster to read-write and the service guarantees that every write committed on the primary is replicated before the switch happens. No data loss. No surprises.

How It Works

Azure DocumentDB’s cross-region replication keeps a replica cluster in a secondary Azure region which is continuously and asynchronously synchronized with your primary. Under normal conditions, the replica trails the primary by a small window (usually in milliseconds) to avoid impacting write performance on the primary, but close enough to make a clean handoff possible.

When you trigger a Graceful Failover, Azure DocumentDB executes a precise, ordered sequence:

1. Drains the replication queue – waiting until the replica in Region B is fully caught up with the former primary.
2. Promotes the replica in Region B to the primary.
3. Demotes the former primary in Region A to read-only and reverses the replication direction.
4. Automatically points the global connection string to the newly promoted primary.

The result is a clean, zero-data-loss region switch. Your application continues operating against the global read-write connection string, which automatically updates to point to the newly promoted cluster with no connection string change required.

Choosing the Right Failover Mode

Graceful Failover is one of three ways a replica cluster can assume the read-write role. Here’s how they compare:

Graceful Failover is the right choice when:

• You’re executing a planned region migration, which is typical during changes in business traffic from one region to another.
• You want to validate your DR runbook without risking data loss
• You’re proactively moving ahead of a scheduled application maintenance window

If an actual regional outage occurs and the primary is unreachable, Forced Promotion or Service-Managed Failover are the appropriate mechanisms. Graceful Failover requires the primary to be reachable in order to drain the queue and is thus not the right choice in that scenario.

What You Need to Use It

Graceful Failover requires cross-region replication to be configured. To use it:

1. Set up cross-region replication with a replica cluster in a secondary Azure region.
2. Use the global read-write connection string in your application, which automatically redirects after the promotion completes.
3. Initiate Graceful Failover via the Azure Portal or programmatically through the management API when you’re ready to switch.

No application-side changes are needed beyond using the global connection string.

In-Region HA and Cross-Region DR: The Full Picture

Graceful Failover addresses planned or proactive region switches, but it works alongside and not instead of in-region high availability (HA). Here’s how the layers fit together:

• In-region HA protects against physical shard failures within your primary region automatically, synchronously, and with zero data loss.
• Graceful Failover gives you a controlled, zero-data-loss path to move your primary workload to a different region on your own terms.
• Service-Managed Failover covers the unplanned scenario where human intervention isn’t fast enough.

Running all three in combination gives you comprehensive coverage across failure scenarios at every scale.

Getting Started

Cross-region replication and Graceful Failover are available across Azure regions that support Azure DocumentDB.

To learn more, see: https://aka.ms/documentdb-graceful-failover

About Azure DocumentDB

Azure DocumentDB is a fully managed document database service for building and modernizing MongoDB-compatible applications. Powered by the open-source DocumentDB engine, it combines familiar APIs, tools, and workflows with Azure’s security, scalability, and operational simplicity. Whether you’re developing new applications or migrating existing MongoDB workloads, Azure DocumentDB helps you get started quickly and scale with confidence.