Cosmos DB emulator overview

Azure Cosmos DB is a fully managed, globally distributed database service designed to provide low-latency and scalable solutions for modern applications. But how do you develop, test, and debug these applications locally without incurring costs or managing live cloud environments? This is where the Cosmos DB Emulator comes into play.

In this blog post, we’ll explore what the Cosmos DB Emulator is, its features, and how you can set it up for local development to simulate the experience of working with Azure Cosmos DB in the cloud.

What is Cosmos DB Emulator?

The Cosmos DB Emulator is a local development tool that provides an environment to build and test applications using Azure Cosmos DB without the need for an internet connection or an Azure subscription. It mimics the behavior and functionality of the real Cosmos DB service, offering the same capabilities and APIs (SQL, MongoDB, Cassandra, Gremlin, and Table APIs) that you would use in a production Cosmos DB instance. It’s an essential tool for developers who want to:

Prototype applications locally.
Run integration tests.
Debug code without consuming cloud resources.

Key Features of Cosmos DB Emulator

The Cosmos DB Emulator offers several features that make it highly effective for local development:

Multi-API Support

Cosmos DB Emulator supports multiple APIs, just like the cloud service. This allows you to work with:

SQL API
MongoDB API
Cassandra API
Gremlin API
Table API

This flexibility makes it possible to develop cross-platform, multi-model applications with the same APIs that will be used in production.

Local Development Environment

The emulator runs entirely on your local machine, which means:

No Cloud Costs: You can develop without incurring any charges from querying or modifying a live Cosmos DB instance.
Faster Development Cycle: Since the emulator runs locally, there is no network latency, which results in faster response times when querying or updating data.
Offline Development: You can continue developing and testing even when you don’t have an active internet connection.

Full Query and Transactional Support

Just like the live Cosmos DB service, the emulator supports:

SQL-like queries on the data.
Partitioning to improve performance and scalability.
Transactions that enable atomicity for multiple operations.

Local UI for Database Management

The Cosmos DB Emulator comes with a built-in, browser-based local UI similar to the Azure portal. Through this interface, you can:

Perform CRUD (Create, Read, Update, Delete) operations on data.
Create and manage databases and containers.
Run queries.

Why Use Cosmos DB Emulator for Development?

Cost Efficiency

One of the biggest benefits of using Cosmos DB Emulator is that it allows developers to build and test their applications without paying for Cosmos DB throughput or storage costs. Since everything runs locally, you can experiment with queries, schema designs, and data structures without worrying about cloud charges.

Accelerated Development

Developing locally with Cosmos DB Emulator speeds up the development process by eliminating the latency involved in making API calls over the internet to cloud-based databases. It’s a much quicker feedback loop when building and debugging applications.

Offline Development

The ability to develop offline is a huge advantage, especially when traveling or working in environments with unreliable internet connections. Developers can continue to build and test applications even without being connected to Azure.

Feature Parity with Cloud Cosmos DB

Cosmos DB Emulator provides near-complete feature parity with the cloud-based version, meaning that applications built and tested locally will behave almost identically when deployed to a live Cosmos DB environment.

Installing and Setting Up Cosmos DB Emulator

Setting up the Cosmos DB Emulator is straightforward. Here’s how you can get it running on your local machine:

Prerequisites

Windows: The emulator is primarily available for Windows, but you can now also use it on Linux and macOS using Docker containers.
.NET Framework: The emulator requires .NET Framework 4.6.1 or later.

Installation on Windows

Download the Emulator: You can download the latest version of the Cosmos DB Emulator from the official Microsoft website.
Run the Installer: Execute the downloaded .exe file and follow the setup instructions.
Launch the Emulator: After installation, launch the emulator, which will start a local instance of Cosmos DB. A browser window will open, displaying the emulator’s local UI for managing databases and data.

Installation on macOS and Linux (via Docker)

For non-Windows users, you can run Cosmos DB Emulator using Docker:

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
docker run \ --publish 8081:8081 \ --publish 10250-10255:10250-10255 \ --name linux-emulator \ --detach \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Once the container is running, navigate to https://localhost:8081/_explorer/index.html to access the emulator UI.

Connecting to Cosmos DB Emulator

When developing locally, you will need to connect your application to the emulator instance by using the following connection string in your configuration:

AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;

This connection string points to the local Cosmos DB Emulator. You can use this in your application’s connection settings.

Running Queries and Managing Data with Cosmos DB Emulator

Once the emulator is running, you can manage your Cosmos DB databases and containers through the local UI or programmatically using the SDKs. Below is an example of how to insert and query data using the Cosmos DB SDK with the emulator

Inserting Data

Here’s a sample code to insert data into a local Cosmos DB container using the SQL API

Create a new console app in .Net core and add package Microsoft.Azure.Cosmos
Use the following code to upsert data in the cosmos db.

using Microsoft.Azure.Cosmos;
using Container = Microsoft.Azure.Cosmos.Container;

using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);
var itemId = new Random().Next().ToString();
var item = new
{
    id = itemId,
    Description = $"rocket-{itemId}"
};

await container.UpsertItemAsync(item);

Console.WriteLine("data inserted successfulyy");
Console.ReadLine();

Conclusion

The Cosmos DB Emulator is an invaluable tool for developers working with Azure Cosmos DB. It provides a powerful local environment that mirrors the capabilities of the cloud-based service, enabling faster, cost-effective development cycles. Whether you’re testing queries, working on prototypes, or debugging your applications, the Cosmos DB Emulator ensures that you can develop locally with confidence before deploying to the cloud.