During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Provisioning Cosmos DB for MongoDB
This guide shows you how to provision Azure Cosmos DB for MongoDB against Locally, then connect to it with mongosh to write and read a document. As with the other guides we're going to use the Azure CLI, but the same resources can be provisioned with HashiCorp Terraform, Pulumi or Bicep too.
Before you start
- The Azure CLI (
az) installed. - The MongoDB Shell (
mongosh) installed. - Locally installed, with Locally Setup completed.
1. Start Locally
Firstly, we need to launch Locally which we can do from a terminal by running:
$
locally build
Once Locally has started, the Locally Dashboard will open automatically:
2. Create a Resource Group
Next we can create the Resource Group to hold the account:
$
locally run az group create -n sample-cosmos-db-for-mongodb -l berlin
There's two things to note here:
- The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with
locally run. - Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with
locally runwhen you do.
3. Create the Cosmos DB Account
Now we can create the account. Passing --kind MongoDB is what makes it a MongoDB account rather than a NoSQL one:
$
locally run az cosmosdb create --name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --kind MongoDB --locations regionName=berlin
{
"note": "some fields skipped for brevity",
"capabilities": [
{
"name": "EnableMongo"
}
],
"documentEndpoint": "https://sample-cosmos-mongo-1.cosmonaut.locally:5665/",
"kind": "MongoDB",
"location": "berlin",
"name": "sample-cosmos-mongo-1",
"provisioningState": "Succeeded",
"resourceGroup": "sample-cosmos-db-for-mongodb",
"type": "Microsoft.DocumentDB/databaseAccounts"
}
The account is served by the Cosmos DB Emulator running on your machine. The documentEndpoint is for the NoSQL API, so we'll get the MongoDB address from the connection string in a moment.
4. Create a database and collection
Next we'll create a database within the account:
$
locally run az cosmosdb mongodb database create --account-name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --name appdb
{
"note": "some fields skipped for brevity",
"id": "/subscriptions/0f766306-391f-4f66-b9ee-927fb2db629c/resourceGroups/sample-cosmos-db-for-mongodb/providers/Microsoft.DocumentDB/databaseAccounts/sample-cosmos-mongo-1/mongodbDatabases/appdb",
"name": "appdb",
"resource": {
"id": "appdb"
},
"resourceGroup": "sample-cosmos-db-for-mongodb",
"type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases"
}
Then a collection inside it. Here we'll shard orders by the customer they belong to:
$
locally run az cosmosdb mongodb collection create --account-name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --database-name appdb --name orders --shard customerId
{
"note": "some fields skipped for brevity",
"id": "/subscriptions/0f766306-391f-4f66-b9ee-927fb2db629c/resourceGroups/sample-cosmos-db-for-mongodb/providers/Microsoft.DocumentDB/databaseAccounts/sample-cosmos-mongo-1/mongodbDatabases/appdb/collections/orders",
"name": "orders",
"resource": {
"id": "orders",
"shardKey": {
"customerId": "Hash"
}
},
"resourceGroup": "sample-cosmos-db-for-mongodb",
"type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections"
}
We can confirm it's there:
$
locally run az cosmosdb mongodb collection list --account-name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --database-name appdb --query "[].{Name:name, ShardKey:keys(resource.shardKey)[0]}" -o table
Name ShardKey
------ ----------
orders customerId
5. Get the connection string
To connect, we need one of the account's connection strings:
$
locally run az cosmosdb keys list --name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --type connection-strings
{
"note": "read-only connection strings skipped for brevity",
"connectionStrings": [
{
"connectionString": "mongodb://sample-cosmos-mongo-1:kEAvLEi%2BBJjT3VXdTHzoY57xJ4Hc19pnXyCh9gjSRHY%[email protected]:5666/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@sample-cosmos-mongo-1@",
"description": "Primary MongoDB Connection String",
"keyKind": "Primary",
"type": "MongoDB"
},
{
"connectionString": "mongodb://sample-cosmos-mongo-1:2FCQHj8uotLsinMJ6vO%2FtiN6JBcVSVkWR2cxmpgwz10%[email protected]:5666/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@sample-cosmos-mongo-1@",
"description": "Secondary MongoDB Connection String",
"keyKind": "Secondary",
"type": "MongoDB"
}
]
}
The MongoDB endpoint has its own hostname, ending -mongo.cosmonaut.locally, and the account key is the password. Let's keep hold of the primary one:
$
export MONGO_URL=$(locally run az cosmosdb keys list --name sample-cosmos-mongo-1 --resource-group sample-cosmos-db-for-mongodb --type connection-strings --query "connectionStrings[0].connectionString" -o tsv)
6. Connect with mongosh
The connection string has ssl=true, and Locally's certificates are signed by its own local CA, so we point mongosh at that with --tlsCAFile. Let's insert an order:
$
mongosh "$MONGO_URL" --tlsCAFile ~/.config/locally/local-ca.pem --quiet --eval 'db.getSiblingDB("appdb").orders.insertOne({customerId: "contoso", item: "coffee", quantity: 2})'
{
acknowledged: true,
insertedId: ObjectId('6ae61b233bb1013a63308b68')
}
And find it again:
$
mongosh "$MONGO_URL" --tlsCAFile ~/.config/locally/local-ca.pem --quiet --eval 'db.getSiblingDB("appdb").orders.find({customerId: "contoso"})'
[
{
customerId: 'contoso',
item: 'coffee',
quantity: 2,
_id: ObjectId('6ae61b233bb1013a63308b68')
}
]
Leave off --eval to get an interactive shell instead. If you've trusted Locally's CA system-wide, mongosh picks it up and you can drop --tlsCAFile too.
Note
%LocalAppData%\locally\local-ca.pem.7. Tidy up
Finally, we can tidy up. To remove the Resource Group and everything within it:
$
locally run az group delete -n sample-cosmos-db-for-mongodb --yes
There's nothing billable to clean up, since everything ran on your machine, but it's still worth checking your teardown scripts work here before you run them against Azure.
Doing this with other tooling
Whilst this guide used the Azure CLI, Cosmos DB for MongoDB works the same way through any of the tooling that Locally supports - Microsoft.DocumentDB/databaseAccounts with a kind of MongoDB, and its child resources, in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way, with only the location changed.
The same goes for your application: a MongoDB driver connects with the connection string above, as long as it trusts Locally's CA.
Next steps
The Cosmos DB Emulator covers what the data plane supports. If you're using the NoSQL API instead, see Provisioning a Cosmos DB Account. To keep the connection string out of your app's settings, store it in a Key Vault.
Should you encounter any issues, please take a look at the troubleshooting section, reach out in our Discord or open an issue and we'll take a look.
Resource types this guide uses
These are the Azure resource types this guide creates in Locally:
- Microsoft.DocumentDB/databaseAccounts
- Microsoft.DocumentDB/databaseAccounts/mongodbDatabases
- Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in