Develop locally using the Azure Cosmos DB emulator
Article
A common use case for the emulator is to serve as a development database while you're building your applications. Using the emulator for development can help you learn characteristics of creating and modeling data for a database like Azure Cosmos DB without incurring any service costs. Additionally, using the emulator as part of an automation workflow can ensure that you can run the same suite of integration tests. You can ensure that the same tests run both locally on your development machine and remotely in a continuous integration job.
Pull the mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux container image using the mongodb tag from the container registry to the local Docker host.
The Docker container variant (Linux or Windows) of the emulator doesn't support the API for Apache Cassandra, API for Apache Gremlin, or API for Table.
To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer.
Tip
The emulator release notes article lists all the available versions and the feature updates that were made in each release.
The Docker container variant of the emulator doesn't support the API for Apache Cassandra.
Start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%\Azure Cosmos DB Emulator path. Use these parameters to configure the emulator:
The Docker container variant of the emulator doesn't support the API for Apache Gremlin.
Start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%\Azure Cosmos DB Emulator path. Use these parameters to configure the emulator:
The Docker container variant of the emulator doesn't support the API for Table.
Start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%\Azure Cosmos DB Emulator path. Use these parameters to configure the emulator:
Navigate to https://localhost:8081/_explorer/index.html to access the data explorer.
The Docker (Windows) container image doesn't support the API for MongoDB.
Start the emulator's executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%\Azure Cosmos DB Emulator path. Use these parameters to configure the emulator:
Description
EnableMongoDbEndpoint
Enables API for MongoDB endpoint at specified MongoDB version.
The Docker container variant (Linux or Windows) of the emulator doesn't support the API for Apache Cassandra, API for Apache Gremlin, or API for Table.
The Windows local installation of the emulator automatically imports the TLS/SSL certificates. No further action is necessary.
The certificate for the emulator is available at the path _explorer/emulator.pem on the running container. Use curl to download the certificate from the running container to your local machine.
You may need to change the host (or IP address) and port number if you have previously modified those values.
Install the certificate according to the process typically used for your operating system. For example, in Linux you would copy the certificate to the /usr/local/share/ca-certificates/ path.
For linux systems, regenerate the certificate bundle by using the appropriate command for your Linux distribution.
For Debian-based Linux systems (for example, Ubuntu), use:
sudo update-ca-certificates
For Red Hat-based Linux systems (for example, CentOS, Fedora), use:
sudo update-ca-trust
For more detailed instructions, consult the documentation specific to your operating system.
The certificate for the emulator is available at the folder C:\CosmosDB.Emulator\bind-mount on the running container. The folder also contains a script to automatically install the certificate.
Use docker cp to copy the entire folder to your local machine.
The Windows local installation of the emulator automatically imports the TLS/SSL certificates. No further action is necessary.
Connect to the emulator from the SDK
Each SDK includes a client class typically used to connect the SDK to your Azure Cosmos DB account. By using the emulator's credentials, you can connect the SDK to the emulator instance instead.
var item = new
{
id = "68719518371",
name = "Kiama classic surfboard"
};
await container.UpsertItemAsync(item);
Run the .NET application.
dotnet run
Warning
If you get a SSL error, you may need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the client's options to disable TLS/SSL validation before creating the client:
If you get a SSL error, you might need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the application to disable TLS/SSL validation before creating the client:
import urllib3
urllib3.disable_warnings()
If you're still facing SSL errors, it's possible that Python is retrieving the certificates from a different certificate store. To determine the path where Python is looking for the certificates, follow these steps:
Important
If you are using a Python virtual environment (venv) ensure it is activated before running the commands!
Open a terminal
Start the Python interpreter by typing python or python3, depending on your Python version.
In the Python interpreter, run the following commands:
from requests.utils import DEFAULT_CA_BUNDLE_PATH
print(DEFAULT_CA_BUNDLE_PATH)
Inside a virtual environment, the path might be (at least in Ubuntu):
Outside of a virtual environment, the path might be (at least in Ubuntu):
/etc/ssl/certs/ca-certificates.crt
Once you identified the DEFAULT_CA_BUNDLE_PATH, open a new terminal and run the following commands to append the emulator certificate to the certificate bundle:
Important
If DEFAULT_CA_BUNDLE_PATH variable points to a system directory, you might encounter a "Permission denied" error. In this case, you will need to run the commands with elevated privileges (as root). Also, you will need to update and regenerate the certificate bundle after executing the provided commands.
# Add a new line to the certificate bundle
echo >> /path/to/ca_bundle
# Append the emulator certificate to the certificate bundle
cat /path/to/emulatorcert.crt >> /path/to/ca_bundle
If you get a SSL error, you may need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the application to disable TLS/SSL validation before creating the client:
Create a new instance of MongoClient using the emulator's credentials.
var client = new MongoClient(
"mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);
db = client["cosmicworks"]
if "cosmicworks" not in client.list_database_names():
db.command(
{
"customAction": "CreateDatabase",
"offerThroughput": 400,
}
)
collection = db["products"]
if "products" not in db.list_collection_names():
db.command({"customAction": "CreateCollection", "collection": "products"})
Use update_one to create a new item in the container.
If you get a SSL error, you may need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the application to disable TLS/SSL validation before creating the client:
var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());
var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());
Create a new item in the table using ExecuteAsync. Use Bind to assign properties to the item.
var item = new
{
id = "68719518371",
name = "Kiama classic surfboard"
};
var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");
var createItemStatement = createItem.Bind(item.id, item.name);
await session.ExecuteAsync(createItemStatement);
Import the cassandra-driver package from the Python Package Index.
pip install cassandra-driver
Create the app.py file.
Import PROTOCOL_TLS_CLIENT, SSLContext, and CERT_NONE from the ssl module. Then, import Cluster from the cassandra.cluster module. Finally, import PlainTextAuthProvider from the cassandra.auth module.
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
Create a new TLS/SSL context variable using SSLContext. Configure the context to not verify the emulator's self-signed certificate.
Create a new keyspace and table using session.execute.
session.execute(
"CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'ba"
"sicclass', 'replication_factor': 1};"
)
session.execute(
"CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, nam"
"e text)"
)
Use session.execute to create a new item in the table.
Import the Client type and auth namespace from the cassandra-driver module.
import { Client, auth } from 'cassandra-driver'
Use PlainTextAuthProvider to create a new object for the emulator's credentials. Use Client to connect to the emulator using the credentials.
const credentials = new auth.PlainTextAuthProvider(
'localhost',
'C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=='
)
const client = new Client({
contactPoints: [
'localhost:10350'
],
authProvider: credentials,
localDataCenter: 'South Central US'
})
Use execute to run a command server-side to create a keyspace and table.
await client.execute(
'CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {\'class\':\'basicclass\', \'replication_factor\': 1};'
)
await client.execute(
'CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)'
)
Use execute again to create a new item with parameters.
If you get a SSL error, you may need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the client to disable TLS/SSL validation:
Prior to starting, the API for Apache Gremlin requires you to create your resources in the emulator. Create a database named db1 and a container named coll1. The throughput settings are irrelevant for this guide and can be set as low as you'd like.
var server = new GremlinServer(
hostname: "localhost",
port: 8901,
username: "/dbs/db1/colls/coll1",
password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);
using var client = new GremlinClient(
gremlinServer: server,
messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);
Create a new instance of TableServiceClient using the emulator's credentials.
var serviceClient = new TableServiceClient(
connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);
If you get a SSL error, you may need to disable TLS/SSL for your application. This commonly occurs if you are developing on your local machine, using the Azure Cosmos DB emulator in a container, and have not imported the container's SSL certificate. To resolve this, configure the client to disable TLS/SSL validation:
To run a continuous integration workload that automatically validates your application, use the Azure Cosmos DB emulator with a test suite from your framework of choice. The Azure Cosmos DB emulator is preinstalled in the windows-latest variant of GitHub Action's hosted runners.