Set up multiple-regional distributed database using Azure Cosmos DB's API for MongoDB

  • Article

APPLIES TO: MongoDB

In this article, we show how to use the Azure portal to setup a multiple-regional distributed database and connect to it using Azure Cosmos DB's API for MongoDB.

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.

    Click the regions in the map to add or remove them

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.

Verifying your regional setup

A simple way to check your multiple-regional configuration with Azure Cosmos DB's API for MongoDB is to run the isMaster() command from the Mongo Shell.

From your Mongo Shell:

   db.isMaster()

Example results:

   {
      "_t": "IsMasterResponse",
      "ok": 1,
      "ismaster": true,
      "maxMessageSizeBytes": 4194304,
      "maxWriteBatchSize": 1000,
      "minWireVersion": 0,
      "maxWireVersion": 2,
      "tags": {
         "region": "China East2"
      },
      "hosts": [
         "vishi-api-for-mongodb-chinaeast.documents.azure.cn:10255",
         "vishi-api-for-mongodb-chinanorth.documents.azure.cn:10255",
         "vishi-api-for-mongodb-chinaeast2.documents.azure.cn:10255"
      ],
      "setName": "globaldb",
      "setVersion": 1,
      "primary": "vishi-api-for-mongodb-chinanorth2.documents.azure.cn:10255",
      "me": "vishi-api-for-mongodb-chinanorth2.documents.azure.cn:10255"
   }

Connecting to a preferred region

The Azure Cosmos DB's API for MongoDB enables you to specify your collection's read preference for a multiple-regionally distributed database. For both low latency reads and multiple-regional high availability, we recommend setting your collection's read preference to nearest. A read preference of nearest is configured to read from the closest region.

var collection = database.GetCollection<BsonDocument>(collectionName);
collection = collection.WithReadPreference(new ReadPreference(ReadPreferenceMode.Nearest));

For applications with a primary read/write region and a secondary region for disaster recovery (DR) scenarios, we recommend setting your collection's read preference to primary preferred. A read preference of primary preferred is configured to read from the secondary region when the primary region is unavailable.

var collection = database.GetCollection<BsonDocument>(collectionName);
collection = collection.WithReadPreference(new ReadPreference(ReadPreferenceMode.SecondaryPreferred));

Lastly, if you would like to manually specify your read regions. You can set the region Tag within your read preference.

var collection = database.GetCollection<BsonDocument>(collectionName);
var tag = new Tag("region", "China North2");
collection = collection.WithReadPreference(new ReadPreference(ReadPreferenceMode.Secondary, new[] { new TagSet(new[] { tag }) }));

That's it, that completes this tutorial. You can learn how to manage the consistency of your multiple-regionally replicated account by reading Consistency levels in Azure Cosmos DB. And for more information about how multiple-regional database replication works in Azure Cosmos DB, see Distribute data multiple-regionally with Azure Cosmos DB.

Next steps

In this tutorial, you've done the following:

  • Configure multiple-regional distribution using the Azure portal
  • Configure multiple-regional distribution using the Azure Cosmos DB's API for MongoDB

You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.

Develop locally with the Azure Cosmos DB emulator

Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.