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, orPython 3.7 or later
- Ensure that all required executables are available in yourPATH.
- 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 theAzure Cosmos DB emulator.
- Run the installer on your local machine withadministrative 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 WindowsStart menu.
- Alternatively, you can start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the%ProgramFiles%\Azure Cosmos DB Emulatorpath.
- 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 URLhttps://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 withAzure 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.
Read more
- Optimize development and testing cost in Azure Cosmos DB
- Understand your Azure Cosmos DB bill
- Optimize request cost in Azure Cosmos DB
- Estimate RU/s using the Azure Cosmos DB capacity planner - Azure Cosmos DB for NoSQL
