Set up Azure Cosmos DB multiple-regional distribution using the API for Table

APPLIES TO: Table

This article covers the following tasks:

Add multiple-region database regions using the Azure portal

Azure Cosmos DB is available in all Azure regions around China. After selecting the default consistency level for your database account, you can associate one or more regions (depending on your choice of default consistency level and multiple-regional distribution needs).

1. In the Azure portal, in the left bar, click Azure Cosmos DB.

2. In the Azure Cosmos DB page, select the database account to modify.

3. In the account page, click Replicate data globally from the menu.

4. In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. There is a cost to adding regions, see the pricing page or the Distribute data multiple-regionally with Azure Cosmos DB article for more information.

   

Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. You can use this option to test the failover process or change the primary write region. Once you add a third region, the Failover Priorities option is enabled on the same page so that you can change the failover order for reads.

Selecting multiple-region database regions

There are two common scenarios for configuring two or more regions:

1. Delivering low-latency access to data to end users no matter where they are located around China
2. Adding regional resiliency for business continuity and disaster recovery (BCDR)

For delivering low-latency to end users, it is recommended that you deploy both the application and Azure Cosmos DB in the regions that correspond to where the application's users are located.

For BCDR, it is recommended to add regions based on the region pairs described in the Cross-region replication in Azure: Business continuity and disaster recovery article.

Connecting to a preferred region using the API for Table

In order to take advantage of the multiple-regional distribution, client applications should specify the current location where their application is running. This is done by setting the CosmosExecutorConfiguration.CurrentRegion property. The CurrentRegion property should contain a single location. Each client instance can specify their own region for low latency reads. The region must be named by using their display names such as "China North".

The Azure Cosmos DB for Table SDK automatically picks the best endpoint to communicate with based on the account configuration and current regional availability. It prioritizes the closest region to provide better latency to clients. After you set the current CurrentRegion property, read and write requests are directed as follows:

• Read requests: All read requests are sent to the configured CurrentRegion. Based on the proximity, the SDK automatically selects a fallback geo-replicated region for high availability.

• Write requests: The SDK automatically sends all write requests to the current write region. In an account with multi-region writes, current region will serve the writes requests as well. Based on the proximity, the SDK automatically selects a fallback geo-replicated region for high availability.

If you don't specify the CurrentRegion property, the SDK uses the current write region for all operations.

For example, if an Azure Cosmos DB account is in "China North" and "China North" regions. If "China North" is the write region and the application is present in "China North". If the CurrentRegion property is not configured, all the read and write requests are always directed to the "China North" region. If the CurrentRegion property is configured, all the read requests are served from "China North" region.

Next steps

In this tutorial, you've done the following: