Manage Azure Cosmos DB with PowerShell

Patrick El-Azem

Patrick

We are excited to announce that you can now manage Azure Cosmos DB resources using the new Az.CosmosDB PowerShell package. This package is currently in public preview and will be generally available (GA) soon!

 

Get Az.CosmosDB

To work with Az.CosmosDB, you will need:

  1. PowerShell. The Az and Az.CosmosDB packages are compatible with Windows PowerShell 5.1 or cross-platform PowerShell 7.
  2. The Az package.
  3. The Az.CosmosDB package. (Note that when Az.CosmosDB becomes GA, the Az package will include it.)

You can work with Az.CosmosDB in your preferred Powershell console or editor. You can also work with Az.CosmosDB directly in the Azure portal Cloud Shell with PowerShell. (Note: Az is automatically installed in Cloud Shell. Before GA, you will need to install Az.CosmosDB separately.)

Check your installations of Az and Az.CosmosDB with Get-InstalledModule (your versions may differ):

Get-InstalledModule output for Az and Az.CosmosDB Powershell packages

 

Use Az.CosmosDB

Now that you have Az.CosmosDB installed, what can you do with it?

You can run a complete set of management operations – create, update, delete, and list – on Azure Cosmos DB accounts, databases, and containers. Management cmdlets are available for all Cosmos DB APIs: Core (SQL), MongoDB, Cassandra, Gremlin, and Table.

Az.CosmosDB cmdlets can also manage:

  • database and container throughput
  • partition keys and unique keys
  • range, composite, and spatial indexes
  • stored procedures and user-defined functions
  • conflict resolution policies
  • virtual network rules
  • and more! See the Az.CosmosDB cmdlet reference for all operations.

 

Combine PowerShell management operations

Az.CosmosDB cmdlets expose different combinations of parameters, or parameter sets. All cmdlets can run with typical value parameters for resource names and configuration settings. Many cmdlets can also run with parameter sets that include a ParentObject or InputObject parameter.

These parameter sets are useful when scripts maintain local state during operations on related resources. For example, let’s add a new database and container to an existing Azure Cosmos DB SQL API account.

First, we retrieve the existing Azure Cosmos DB account using Get-AzCosmosDBAccount and set the output to a local variable:

$account = Get-AzCosmosDBAccount -ResourceGroupName "myResourceGroup" -Name "ps-cosmos-db"

Next, we create a new database in the account using New-AzCosmosDBSqlDatabase, pass $account for the ParentObject parameter, and set the output to another local variable:

$database = New-AzCosmosDBSqlDatabase -ParentObject $account -Name "myDatabaseName"

Finally, we create a new container in the database using New-AzCosmosDBSqlContainer, passing $database for the ParentObject parameter:

New-AzCosmosDBSqlContainer -ParentObject $database -Name "myContainerName" -PartitionKeyKind "Hash" -PartitionKeyPath "/myPartitionKey" -Throughput 400

Note that we did not set the output of New-AzCosmosDBSqlContainer to a local variable. We do not have further management steps, so another local variable was not needed. Like all New-AzCosmosDB* cmdlets, New-AzCosmosDBSqlContainer outputs an object reflecting the updated state of the resource.

Similarly, Update-AzCosmosDB* cmdlets output objects reflecting the updated state of the resources. You can use these outputs to maintain local state and combine management operations on related resources in your scripts.

Powershell console showing multiple Az.CosmosDB cmdlets using ParentObject parameter and local variables

 

Work with Samples

To get you started, PowerShell samples for Azure Cosmos DB management are available for each of the Azure Cosmos DB APIs:

 

References

 

0 comments

Leave a comment