Cosmos DB Emulator and Local Development

The Azure Cosmos DB Emulator is a local desktop application that provides a high-fidelity emulation of the Azure Cosmos DB service. It runs on Windows, macOS, and Linux (via a Docker container). The emulator supports most of the features of the cloud service, including:

The emulator uses a local SQLite database to store data and metadata. When you send a request via the Cosmos DB SDK or REST API to https://localhost:8081, the emulator processes it using the same query engine and indexing logic as the cloud service. It exposes the same REST API endpoints and SDK client configurations. The emulator's default account key is a well-known base64-encoded string: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. This key is used for authentication in local development.

The emulator simulates the Cosmos DB resource hierarchy:

Windows Installation:

Docker (Linux/macOS/Windows):

docker run -p 8081:8081 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 -p 8901:8901 -p 8902:8902 -m 3g --cpus=2 --name=cosmosdb mcr.microsoft.com/cosmosdb/linux/azure-cosmosdb-emulator

This maps all API ports and allocates 3GB memory and 2 CPUs.

Verification:

using Microsoft.Azure.Cosmos;
CosmosClient client = new CosmosClient("https://localhost:8081", "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

The emulator integrates with: - Azure SDKs: The same NuGet packages (e.g., Microsoft.Azure.Cosmos) work against both the emulator and cloud. Simply change the URI and key. - Azure Functions: You can run Cosmos DB-triggered functions locally using the emulator as the trigger source. - Azure DevOps CI/CD: Use the emulator Docker image in build pipelines to run integration tests without provisioning a real Cosmos DB account. - Entity Framework Core: The Cosmos DB provider for EF Core works with the emulator.

The AZ-204 exam expects you to:

A fintech startup building a transaction processing system uses Cosmos DB for its low-latency writes. Developers often work on flights or in areas with poor internet connectivity. They use the Cosmos DB emulator on their laptops to develop and run unit tests locally. Each developer runs the emulator via Docker, mapping ports to avoid conflicts. They use the /AllowNetworkAccess flag so that other services (like a local API gateway) can also connect. The emulator's SQLite backend provides enough throughput for their small test datasets (a few hundred transactions). They discovered that the emulator's change feed works differently under high partition counts, so they limit their test containers to a single partition. When they push code, the CI/CD pipeline spins up a fresh emulator container in Azure DevOps, runs integration tests, and tears it down. This approach saved them thousands of dollars in Cosmos DB costs during development.

A large e-commerce company uses Cosmos DB for product catalog and inventory. They have a strict policy that no production resources are used for testing. Their CI/CD pipeline uses the Cosmos DB emulator Docker image to run automated integration tests. The pipeline uses a docker run command with resource limits (-m 4g --cpus=4) to ensure consistent performance. They pre-populate the emulator with a seed dataset using the bulk import feature. Tests cover CRUD operations, stored procedures, and change feed scenarios. They encountered an issue where the emulator's self-signed certificate caused SSL errors in their .NET Core test runner. They resolved it by adding the emulator's certificate to the Docker container's trusted root store via a custom Dockerfile. They also learned that the emulator's maximum throughput of 10,000 RU/s is insufficient for load testing, so they use a separate cloud test account for performance tests.

A mobile app backend uses both SQL API for core data and MongoDB API for analytics. Developers use the emulator to develop and test both APIs simultaneously. They start the emulator with default settings, which opens SQL on port 8081 and MongoDB on port 10255. In their code, they configure two separate clients: one for SQL and one for MongoDB. They found that while the emulator supports MongoDB wire protocol, it does not support all MongoDB aggregation pipeline stages — a known limitation. They had to adjust their queries to work within the emulator's capabilities. This early detection saved them from deploying broken code to production. They also use the emulator's UI to explore data across both APIs, which the cloud portal does not offer for MongoDB.