Change failover priority or trigger failover for an Azure Cosmos DB account with single write region by using PowerShell

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table


We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

This sample requires Azure PowerShell Az 5.4.0 or later. Run Get-Module -ListAvailable Az to see which versions are installed. If you need to install, see Install Azure PowerShell module.

Run Connect-AzAccount to sign in to Azure.

Sample script


Any change to a region with failoverPriority=0 triggers a manual failover and can only be done to an account configured for manual failover. Changes to all other regions simply changes the failover priority for an Azure Cosmos DB account.


This sample demonstrates using a API for NoSQL account. To use this sample for other APIs, copy the related properties and apply to your API specific script

# Reference: Az.CosmosDB |
# --------------------------------------------------
# Purpose
# Update Cosmos DB account: Change region failover priority.
# Note: updating location at priority 0 triggers a failover to the new location
# --------------------------------------------------
# Variables - ***** SUBSTITUTE YOUR VALUES *****
$resourceGroupName = "myResourceGroup" # Resource Group must already exist
$accountName = "myaccount" # Must be all lower case
$locations = @("West US", "East US") # Regions ordered by UPDATED failover priority
# --------------------------------------------------

# Get existing Cosmos DB account
$account = Get-AzCosmosDBAccount -ResourceGroupName $resourceGroupName -Name $accountName

# Update account failover priority
Update-AzCosmosDBAccountFailoverPriority -InputObject $account -FailoverPolicy $locations

Clean up deployment

After the script sample has been run, the following command can be used to remove the resource group and all resources associated with it.

Remove-AzResourceGroup -ResourceGroupName "myResourceGroup"

Script explanation

This script uses the following commands. Each command in the table links to command specific documentation.

Command Notes
Azure Cosmos DB
Get-AzCosmosDBAccount Lists Azure Cosmos DB Accounts, or gets a specified Azure Cosmos DB Account.
Update-AzCosmosDBAccountFailoverPriority Update the failover priority order of an Azure Cosmos DB Account's regions.
Azure Resource Groups
Remove-AzResourceGroup Deletes a resource group including all nested resources.

Next steps

For more information on the Azure PowerShell, see Azure PowerShell documentation.