Local Development using Azure Cosmos DB Emulator at no Cost

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Community Hub.

In our previous blogs we introduced you to what is Azure Cosmos DB and Azure Cosmos DB APIs like Azure Cosmos DB for PostgreSQL, Azure Cosmos DB for Apache Gremlin, Azure Cosmos DB for MongoDB. In this blog we are going to introduce you Azure Cosmos DB Emulator which will help to run Azure Cosmos DB offline and do local development with ease.

Benefits of Azure Cosmos DB Emulator

Local Development Environment: The emulator provides a local environment that closely emulates the Azure Cosmos DB service. You can use it to develop and test your applications without needing an active Azure subscription or incurring any service costs.
Cost-Free Testing: By using the emulator, you can write and test code that interacts with Azure Cosmos DB APIs even when you have no network connection. This allows you to avoid any costs associated with using the actual cloud service
Automation Workflow Support: Incorporating the emulator into your automation workflows enables consistent testing across local development machines and remote continuous integration jobs.

Prerequisites

.NET 6 or later, Node.js LTS, or Python 3.7 or later

Ensure that all required executables are available in your PATH.

Windows emulator

64-bit Windows Server 2016, 2019, Windows 10, or Windows 11.
Minimum hardware requirements:

2-GB RAM
10-GB available hard disk space

What will be covered

Installation process of Azure Cosmos DB Emulator
Using Explorer in Azure Cosmos DB Emulator
Connecting Azure Cosmos DB Emulator with Azure Data Studio
Consuming Azure Cosmos DB using Azure Cosmos DB client library for JavaScript/TypeScript

Installation process of Azure Cosmos DB Emulator

Visit this page
Under choose an API, select your preferred API, I will go with NoSQL.
You can run the emulator in docker(both linux & windows) or windows via local installation which we are going to do.
Download the Azure Cosmos DB emulator.
Run the installer on your local machine with administrative privileges.
The emulator automatically installs the appropriate developer certificates and configures firewall rules on your local machine.

Start the emulator

Start the emulator by selecting the application in the Windows Start menu.
Alternatively, you can start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%\Azure Cosmos DB Emulator path.
Also, you can start the emulator from the command-line. Use these parameters to configure the emulator ie you can specify the port to use for the API for NoSQL endpoint. More about emulator cli commands

Microsoft.Azure.Cosmos.Emulator.exe /Port=65000

The emulator automatically opens the data explorer using the URL https://localhost:8081/_explorer/index.html
If you're using docker you must configure emulator's TLS/SSL certificate but Windows local installation of the emulator automatically imports the TLS/SSL certificates. No further action is necessary.
You should be welcomed by this familiar screen.

Using Explorer in Azure Cosmos DB Emulator

Create a database, container, select database throughput, database max RU/s and partition key. Then press okey

You can confirm that you have created the database and container by

Let’s create an item in our container. Click on items then new item and paste below json object and save.

{ "eventId": "unique_event_id", "eventName": "Marathon", "eventDate": "2024-05-20", "participants": [ { "participantId": "participant1", "name": "Alice", "score": 1200 }, { "participantId": "participant2", "name": "Bob", "score": 1100 } ] }

Run query to select all items in our container. Click on run query, write your query and execute the query.

You can access the Query Stats like RUs usage. You can also export the stats.

Connecting Azure Cosmos DB Emulator with Azure Data Studio

Download Azure data studio here and install it in your machine.

Go to Azure Cosmos DB Emulator quickstart page and copy the Primary Connection String

Open Azure data studio. Under extensions search Azure Cosmos DB and install the extension.

Click on connections, create new connection, then select Azure Cosmos DB for NoSQL, select connection string, the paste the Primary Connection String we copied in the emulator. Press connect.

The connection is successful, and you can easily use Azure Data Studio if its your preferred tool and create databases, containers make queries etc.

U can take advantage of the import sample data button to get sample data to get started. A new container will be created with data.

Consuming Azure Cosmos DB using Azure Cosmos DB client library for JavaScript/TypeScript

We are going to use Azure Cosmos DB client library for JavaScript/TypeScript which is an SDK intended for JavaScript/TypeScript applications to interact with Azure Cosmos DB APIs. With it we can
- Create Cosmos DB databases and modify their settings.
- Create and modify containers to store collections of JSON documents.
- Create, read, update, and delete the items (JSON documents) in your containers.
- Query the documents in your database using SQL-like syntax
You can read more about this SDK here.
I have prepared a small workshop here, to help you interact with Azure Cosmos DB Emulator with a simple API starter code which you can hook up with hono or express or your favorite JavaScript / Typescript backend.

In client.config.ts, we have just initialized our cosmosClient and passed in endpoint and key stored in .env file. NB: I have added agent property to allow us to use the "https:" from our emulator smoothly in our local development.
I have imported client.config.ts into db.config.ts to help us create our database and container programtically. Lastly I’m using data.ts to store sample objects we can use to save in our container.

In my index.ts, I have included several functions to help interact with our emulator. If you run pnpm run dev
or npm run dev you will get [ ] meaning our container is empty but it have been created together with the database.

If you uncomment createFamilyMember(familyMember) and alsorun you code. You should get one family member create

You can confirm this on the Emulators explorer.