Manage Azure Cosmos DB with PowerShell
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!
To work with Az.CosmosDB, you will need:
- PowerShell. The Az and Az.CosmosDB packages are compatible with Windows PowerShell 5.1 or cross-platform PowerShell 7.
- The Az package.
- 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):
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
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
$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
$database for the
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-AzCosmosDBSqlContainer outputs an object reflecting the updated state of the resource.
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.
Work with Samples
To get you started, PowerShell samples for Azure Cosmos DB management are available for each of the Azure Cosmos DB APIs:
- Manage Azure Cosmos DB SQL API resources using PowerShell
- Az.CosmosDB cmdlet reference
- Az.CosmosDB source code on GitHub
- Bugs or feature requests on GitHub