Cosmos DB constitutes one of the Azure foundational services, which ensures its availability in every existing and newly provisioned Azure region. It delivers a wide range of advantages over traditional SQL and NoSQL-based data stores, including, for example, support for multiple consistency levels, latency and throughput guarantees, policy-based geo-fencing, automatic scaling, and multi-master replication model. However, it also represents significant departure from the traditional database management and development approach that most database administrators are familiar with. In this article, we will review several offerings that you can use at no cost to gain hands-on experience with Cosmos DB.
The most straightforward way to administer and interact with Azure Cosmos DB without incurring any monetary charges involves signing up for an Azure Trial subscription, which (at the time this article was written) provides $200 worth of credits during its first month and a 12-month period during which you are entitled to use a subset of services without having to pay for their usage. These free services include Azure Cosmos DB databases of up to 5 GB in size and serving up to 400 request units. As the result, you can implement and test majority of features available with the full-fledged subscriptions, excluding primarily those related to scalability and availability. This approach is geared primarily towards database administrators with no prior experience with Azure Cosmos DB.
Another option, directed towards those interested in Cosmos DB data-related tasks is Cosmos DB Query Playground. This interactive web site helps you to learn about Cosmos DB NoSQL query syntax by providing a set of sample JSON-formatted documents and examples of most common queries. It also allows you to construct custom queries, guiding you through such tasks as filtering, ordering, or geo-spatial indexing and proximity-based operations.
If you are a developer, you will likely be best served by taking advantage of the third option in the form of Cosmos DB Emulator. This allows you to create a single Cosmos DB account with multiple containers (up to 25 fixed or 5 unlimited) and databases, as well as develop applications that interact with them locally on your computer, without relying on Internet connectivity or an Azure subscription. You have the ability to develop against SQL API, as well as Table, MongoDB, Cassandra, and Gremlin. While the underlying implementation of Cosmos DB functionality is obviously different from that of the Azure-based service, the emulation hides all differences, yielding full compatibility from the development standpoint. However, it is important to note that (not surprisingly) features that depend on access to cloud infrastructure and multiple accounts, such as scaling, replication, performance guarantees, and consistency levels are not available.
The emulator is supported only on 64-bit versions of Windows (including Windows Server 2012 R2, Windows Server 2016, Windows Server 2019, and Windows 10) and requires at minimum 2 GB of RAM and 10 GB of free disks space. It is available as a Microsoft Installer package from Microsoft Download Centeror as a Docker for Windows container from Microsoft Container Registry. When using the Microsoft Installer package, you must perform the installation in the security context of an account with local administrative privileges.
Once the installation completes, you can launch the emulator from the Start menu (as any other desktop app) or by running the C:Program FilesAzure Cosmos DB EmulatorCosmosDB.Emulator.execommand line utility. At that point, you will be able to access the emulator user interface in a browser window via https://localhost:8081/_explorer/index.html URL (note that Data Explorer part of that interface is available when using SQL API only). You also have the ability to manage emulator by using PowerShell, leveraging the Microsoft.Azure.CosmosDB.Emulator module included in the installation. The module supports basic administrative tasks, such as starting, stopping or uninstalling the emulator.
In order to connect to the underlying service, you need to provide the master key. The emulator relies on a well-known key value (C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==), but you have the option of modifying it by running CosmosDB.Emulator.exe with the GenKeyFile option. While connectivity is, be default, limited to the local computer (the emulator listens to incoming requests on TCP port 8081), it is possible to allow inbound traffic from the local network by specifying the /AllowNetworkAccessoption when starting the emulator.
Depending on your choice of programming platform, it might be necessary to carry out post-installation certificate management tasks. This is related to the fact that initial setup of the emulator generates a certificate that is subsequently used to facilitate SSL-based communication with the Cosmos DB account. This certificate is stored in the Local Machine private certificate store. While the store is readily accessible by .NET based code, it does not integrate with Python or Java (which rely on their own certificate stores). To address this incompatibility, you will need to export the certificate and then import it into the store corresponding to your preferred run-time.
With the emulator installed and running, you are ready to start developing Cosmos DB bound applications. Specifics are dependent on the API you chose when creating target Cosmos DB account. For example, for SQL API, you can use either Azure Cosmos DB SDK (available from Nuget repository or Azure Cosmos DB REST API (documented at Azure Cosmos DB: REST API Reference). For Table API, you can use Microsoft Azure Cosmos DB Table Library for .NET, available from (available from Nuget repository). When working with MongoDB, you can leverage MongoDB.NET driver downloadable from MongoDB Ecosystem. To work with Cassandra API, install Python and Cassandra CLI/CQLSH. For Gremlin API development, install apache-tinkerpop-gremlin-console-3.3.4.
Cosmos DB emulator facilitates data transfers by utilizing the functionality of Azure Cosmos DB Data Migration Tool. This open source tool, available from GitHub, supports a range of data sources, including Azure tables, MongoDB databases, SQL Server databases, CSV and JSON files, and Amazon DynamoDB. It also allows you to transfer data to and from Azure Cosmos DB.
In an upcoming articles, I will step through developing sample Cosmos DB applications by using the emulator.
