cosmos_db_ex

This (unofficial) client library enables client applications targeting Elixir to connect to Azure Cosmos DB via the SQL REST API.

Most if not all of this libraries functionality is accessible from the CosmosDbEx module.

Notice

This library is definitely in alpha stage. There are no optimizations, and there are probably a whole lot of areas that can be improved or changed completely.

I'm looking for any and all feedback: good, bad, or ugly.

Configuration

There are specific configuration values that must be present in order to communicate with your instance of Cosmos Db. They are:

• COSMOS DB KEY - This is either the primary or secondary Read-Write key of your database. You can find these keys under the 'Keys' tab of your databases settings. This value can be set in your apps config using :cosmos_db_key or as an environment variable named COSMOS_DB_KEY.

• COSMOS DB HOST URL - This is the URI to your Cosmos DB instance. The value can be found under the Essentials section of your Cosmos Db Overview. This value can be set in your apps config using :cosmos_db_host_url or as an environment variable named COSMOS_DB_HOST_URL.

Example using your apps configuration settings:

 config :cosmos_db_ex,
  cosmos_db_key: "{your_primary_or_secondary_key_here}",
  cosmos_db_host_url: "https://your-cosmos-db.documents.azure.com/",

Remember that your keys are secrets that should never be saved in any version control system. If you're going to use the config option please take caution and look at using a config provider that retrieves the secrets from a vault or the environment.

Status

Installation

The package can be installed by adding cosmos_db_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:cosmos_db_ex, "~> 0.1.1"}
  ]
end

Usage:

Right now this library only implements the very basics needed to create a document and to retrieve documents. When I say 'basics' I mean only the basics. So far there are only the following functions available:

*get_document: Retreives a document by it's id and partition key.

*get_documents: Retrieves all documents in a container.

*query: Gives you an additional option to write your own query to send to CosmosDb. This is probably going to be your go-to function.

*create_document - Create a document, in a container, using a Map and partition key.

Containers

Everything requires a container (could also be called "collection"). A container is nothing more than a struct with the database name and container name. This is something that could probably be done better, and may change in a future version.

Please see the docs at hex.pm for examples: cosmos_db_ex

Road Map (TODOs):

As this is an early version, there is a boat load of work that still needs to be done. The next versions will concentrate on the following:

• Update create_document to work with structs as well as maps.

• Add the ability to create new database and containers on startup, if they don't already exist.

• Add Upsert.

• Add ability to set consistency levels.

• Add ability to use session tokens.