Provisioning Cosmos DB for MongoDB

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

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:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. 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 run when 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:

{
  "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:

{
  "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:

{
  "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:

Name    ShardKey
------  ----------
orders  customerId

5. Get the connection string

To connect, we need one of the account's 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:

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:

{
  acknowledged: true,
  insertedId: ObjectId('6ae61b233bb1013a63308b68')
}

And find it again:

[
  {
    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.

7. Tidy up

Finally, we can tidy up. To remove the Resource Group and everything within it:

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.

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