package azure-cosmos-db

All checked builds pass
  1. Overview
  2. Docs
Azure cosmos db interface

Install

dune-project
 Dependency

Authors

Maintainers

Sources

0.5.1.tar.gz
md5=d0e9a1362018eb772de3d891874f5955
sha512=f9aecabe498877967984d16b4445b1f7658d3ec1e6784a431343dc5f7c5fae53fabcdf792c5419578f9d9e5355e5c43edd96375c342d59ab97882bc09f756cff

Description

Provides an interface to the Azure Cosmos db.

Added to opam-repository:

README

Coverage Status

Azure cosmos db

Provides an interface to Microsoft Azure Cosmos db.

Documentation

Microsoft documentation

API documentation

Quick start

module MyAuthKeys : Auth_key = struct
  let master_key = "key guid found in azure portal"
  let endpoint = "endpoint found in azure portal (e.g. endpoint.documents.azure.com)"
end

module D = Database (MyAuthKeys)
D.list_databases ()

Resource tokens

A resource token minted through User/Permission can be used instead of the master key. The token is sent as-is in the authorization header, so only the resources it was granted access to are reachable:

module D_token =
  Database_as ((val credentials_of_token ~endpoint "type=resource&ver=1&sig=..."))

(* Refresh the token on every request, e.g. from a token broker: *)
module D_refreshing =
  Database_as ((val credentials_of_token_provider ~endpoint fetch_token))

Permission tokens expire after about an hour by default; pass ?expiry_seconds (1..18000) to Permission.create, Permission.get, or Permission.replace to choose the lifetime.

Entra ID (AAD) authentication

Accounts created with disableLocalAuth reject the master key entirely and only accept Microsoft Entra ID bearer tokens (type=aad). Unlike resource tokens, an Entra token authorizes every operation, including list_databases, User, Permission and Offer.

The SDK can acquire and refresh tokens itself from a service principal's client credentials:

module Sp = struct
  let endpoint = "https://acct.documents.azure.com"
  let tenant_id = "…"
  let client_id = "…"
  let client_secret = "…"
end

module Db = Database_aad (Sp)
(* The first request acquires and caches a token; it is refreshed before
   expiry. *)

Or bring a token you obtain yourself — Azure CLI, managed identity, or a corporate token broker:

(* az account get-access-token --resource https://cosmos.azure.com *)
module D_aad =
  Database_as ((val credentials_of_aad_token ~endpoint "<access token>"))

(* Callers running their own refresh loop keep the getter synchronous: *)
module D_aad_refreshing =
  Database_as ((val credentials_of_aad_token_provider ~endpoint fetch_aad_token))

The Entra identity needs a data-plane role assignment on the account, e.g. Cosmos DB Built-in Data Contributor (control-plane Reader/Contributor roles are not sufficient — requests return 401/403 without one). Token-endpoint HTTP failures surface as Azure_error carrying the token endpoint's status code; network failures are Connection_error or Timeout_error. A data-plane 401/403 stays Azure_error.

Change feed

The pull-model change feed returns the latest version of changed documents. Treat 304 Not Modified as the normal idle result, and persist the returned ETag checkpoint in the application:

let%lwt first = D.Collection.Change_feed.read
  ~start_from:D.Collection.Change_feed.Start_from.Now
  "my-database" "my-collection"
in
match first with
| Ok (304, _headers, None) -> Lwt.return_unit
| Ok (200, _headers, Some page) ->
    (* Process [page.documents], then persist [page.continuation]. *)
    let%lwt next = D.Collection.Change_feed.read
      ~start_from:
        (D.Collection.Change_feed.Start_from.Continuation page.continuation)
      "my-database" "my-collection"
    in
    ignore next;
    Lwt.return_unit
| Error _error -> Lwt.fail_with "Change feed request failed"

The checkpoint is the caller's responsibility. Ordering is guaranteed only within a partition key. For independent partition-range checkpoints, enumerate the ranges and fan out explicitly with the backend's IO.parallel_map:

let%lwt ranges = D.Collection.Partition_key_range.ids
  "my-database" "my-collection"
in
(* Keep one checkpoint per range while polling each range independently. *)

Latest-version mode does not surface deletes. If deletions must be represented in the feed, use a soft-delete flag and TTL instead.

Throughput management

Offers expose provisioned throughput for databases and collections:

let%lwt throughput =
  D.Offer.get_throughput "my-database" "my-collection"
in
let%lwt updated =
  D.Offer.set_throughput "my-database" "my-collection"
    (D.Offer.Throughput.Manual 500)
in
match (throughput, updated) with
| Ok (_, current), Ok (_, offer) -> Lwt.return (current, offer)
| Error _error, _ | _, Error _error -> Lwt.fail_with "Cosmos request failed"

Offer operations require master-key authentication. Serverless accounts do not expose provisioned-throughput offers, so lookup functions return None.

Dependencies (7)

  1. cryptokit
  2. cohttp
  3. uri
  4. base64 >= "3.5.0"
  5. atdgen >= "2.0.0"
  6. ocaml >= "4.14.0"
  7. dune >= "3.21"

Dev Dependencies (3)

  1. odoc with-doc
  2. ocamlformat with-test & = "0.28.1"
  3. bisect_ppx with-test

Optional Dependencies

None

Used by (2)

  1. azure-cosmos-db-eio >= "0.5.1"
  2. azure-cosmos-db-lwt >= "0.5.1"

Conflicts (1)

  1. result < "1.5"

Build status

Results of building azure-cosmos-db with each compiler on check.ci.ocaml.org, run of against opam-repository 8d8d144. All results for this package.

Each result links to its build log. To keep crawlers from overloading the site, build logs require a GitHub sign-in (see ocurrent/opam-health-check). On your first log, GitHub asks you to “Authorize opam-health-check”, the OCurrent app that runs these checks; it sees only your public profile, not your repositories. The sign-in lasts 30 days.

Version OCaml 4.11 OCaml 4.14 OCaml 5.2 OCaml 5.4 OCaml 5.5
0.5.1 (this version) n/a good good good good
0.4.0 good good good good good
  • good Package successfully built
  • partial One of the dependencies failed to build
  • bad Package failed to build
  • n/a Package is not available in this environment
  • internal Internal failure