Automate Azure DocumentDB account management using Azure CLI 2.0

The following guide describes commands to automate management of your DocumentDB database accounts using the DocumentDB preview commands available in Azure CLI 2.0. It also includes commands to manage account keys and failover priorities in multi-region database accounts. Updating your database account enables you to modify consistency policies and add/remove regions. For cross-platform management of your DocumentDB database account, you can use either Azure Powershell, the Resource Provider REST API, or the Azure portal.

Getting started

Follow the instructions in How to install and configure Azure CLI 2.0 to set up your development environment with Azure CLI 2.0.

Log in to your Azure account by executing the following command and following the on-screen steps.

az login

If you do not already have an existing resource group, create one:

az group create --name <resourcegroupname> --location <resourcegrouplocation>
az group list

The <resourcegrouplocation> must be one of the regions in which DocumentDB is generally available. The current list of regions is provided on the Azure Regions page.

Notes

  • Execute 'az documentdb -h' to get a full list of available commands or visit the reference page.
  • Execute 'az documentdb -h' to get a list of details of the required and optional parameters per command.

Create a DocumentDB database account

This command enables you to create a DocumentDB database account. Configure your new database account as either single-region or multi-region with a certain consistency policy.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.
    --default-consistency-level   : Default consistency level of the DocumentDB database account.
                                    Allowed values: BoundedStaleness, Eventual, Session, Strong.
    --ip-range-filter             : Firewall support. Specifies the set of IP addresses or IP
                                    address ranges in CIDR form to be included as the allowed list
                                    of client IPs for a given database account. IP addresses/ranges
                                    must be comma separated and must not contain any spaces.
    --kind                        : The type of DocumentDB database account to create.  Allowed
                                    values: GlobalDocumentDB, MongoDB, Parse.  Default:
                                    GlobalDocumentDB.
    --locations                   : Space separated locations in 'regionName=failoverPriority'
                                    format. E.g "East US"=0 "West US"=1. Failover priority values
                                    are 0 for write regions and greater than 0 for read regions. A
                                    failover priority value must be unique and less than the total
                                    number of regions. Default: single region account in the
                                    location of the specified resource group.
    --max-interval                : When used with Bounded Staleness consistency, this value
                                    represents the time amount of staleness (in seconds) tolerated.
                                    Accepted range for this value is 1 - 100.  Default: 5.
    --max-staleness-prefix        : When used with Bounded Staleness consistency, this value
                                    represents the number of stale requests tolerated. Accepted
                                    range for this value is 1 - 2,147,483,647.  Default: 100.

Examples:

az documentdb create -g rg-test -n docdb-test
az documentdb create -g rg-test -n docdb-test --kind MongoDB
az documentdb create -g rg-test -n docdb-test --locations "East US"=0 "West US"=1 "South Central US"=2
az documentdb create -g rg-test -n docdb-test --ip-range-filter "13.91.6.132,13.91.6.1/24"
az documentdb create -g rg-test -n docdb-test --locations "East US"=0 "West US"=1 --default-consistency-level BoundedStaleness --max-interval 10 --max-staleness-prefix 200

Notes

  • The locations must be regions in which DocumentDB is generally available. The current list of regions is provided on the Azure Regions page.
  • To enable portal access, include the IP address for the Azure portal for your region in the ip-range-filter, as specified in Configuring the IP access control policy.

Update a DocumentDB database account

This command enables you to update your DocumentDB database account properties. This includes the consistency policy and the locations which the database account exists in.

Note

This command enables you to add and remove regions but does not allow you to modify failover priorities. To modify failover priorities, see below.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.
    --default-consistency-level   : Default consistency level of the DocumentDB database account.
                                    Allowed values: BoundedStaleness, Eventual, Session, Strong.
    --ip-range-filter             : Firewall support. Specifies the set of IP addresses or IP address
                                    ranges in CIDR form to be included as the allowed list of client
                                    IPs for a given database account. IP addresses/ranges must be comma
                                    separated and must not contain any spaces.
    --locations                   : Space separated locations in 'regionName=failoverPriority' format.
                                    E.g "East US"=0. Failover priority values are 0 for write regions
                                    and greater than 0 for read regions. A failover priority value must
                                    be unique and less than the total number of regions.
    --max-interval                : When used with Bounded Staleness consistency, this value represents
                                    the time amount of staleness (in seconds) tolerated. Accepted range
                                    for this value is 1 - 100.
    --max-staleness-prefix        : When used with Bounded Staleness consistency, this value represents
                                    the number of stale requests tolerated. Accepted range for this
                                    value is 1 - 2,147,483,647.

Examples:

az documentdb update -g rg-test -n docdb-test --locations "East US"=0 "West US"=1 "South Central US"=2
az documentdb update -g rg-test -n docdb-test --ip-range-filter "13.91.6.132,13.91.6.1/24"
az documentdb update -g rg-test -n docdb-test --default-consistency-level BoundedStaleness --max-interval 10 --max-staleness-prefix 200

Add/remove region from a DocumentDB database account

To add or remove region(s) from your existing DocumentDB database account, use the update command with the --locations flag. The example below shows how to create a new account and subsequently add and remove regions from that account.

Example:

az documentdb create -g rg-test -n docdb-test --locations "East US"=0 "West US"=1
az documentdb update -g rg-test -n docdb-test --locations "East US"=0 "North Europe"=1 "South Central US"=2

Delete a DocumentDB database account

This command enables you to delete an existing DocumentDB database account.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.

Example:

az documentdb delete -g rg-test -n docdb-test

Get properties of a DocumentDB database account

This command enables you to get the properties of an existing DocumentDB database account.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.

Example:

az documentdb show -g rg-test -n docdb-test

List account keys

When you create a DocumentDB account, the service generates two master access keys that can be used for authentication when the DocumentDB account is accessed. By providing two access keys, DocumentDB enables you to regenerate the keys with no interruption to your DocumentDB account. Read-only keys for authenticating read-only operations are also available. There are two read-write keys (primary and secondary) and two read-only keys (primary and secondary).

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.

Example:

az documentdb list-keys -g rg-test -n docdb-test

List connection strings

For MongoDB accounts, the connection string to connect your MongoDB app to the database account can be retrieved using the following command.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.

Example:

az documentdb list-connection-strings -g rg-test -n docdb-test

Regenerate account key

You should change the access keys to your DocumentDB account periodically to help keep your connections more secure. Two access keys are assigned to enable you to maintain connections to the DocumentDB account using one access key while you regenerate the other access key.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.
    --key-kind          [Required]: The access key to regenerate.  Allowed values: primary, primaryReadonly,
                                    secondary, secondaryReadonly.

Example:

az documentdb regenerate-key -g rg-test -n docdb-test --key-kind secondary

Modify failover priority of a DocumentDB database account

For multi-region database accounts, you can change the failover priority of the various regions which the DocumentDB database account exists in. For more information on failover in your DocumentDB database account, see Distribute data globally with DocumentDB.

Arguments
    --name -n           [Required]: Name of the DocumentDB database account.
    --resource-group -g [Required]: Name of the resource group.
    --failover-policies [Required]: Space separated failover policies in 'regionName=failoverPriority' format.
                                    E.g "East US"=0 "West US"=1.

Example:

az documentdb failover-priority-change "East US"=1 "West US"=0 "South Central US"=2

Next steps

Now that you have a DocumentDB account, the next step is to create a DocumentDB database. You can create a database by using one of the following:

After creating your database, you need to add one or more collections to the database, then add documents to the collections.

After you have documents in a collection, you can use DocumentDB SQL to execute queries against your documents by using the Query Explorer in the portal, the REST API, or one of the SDKs.

To learn more about DocumentDB, explore these resources: