A driver for TypeDB 3.12 and newer, built on the TypeDB HTTP API.

Older 3.x is not supported; see the README for what breaks and why.

Getting started

Add the connection to your supervision tree:

children = [
  {TypeDB,
   url: "http://localhost:8000",
   username: "admin",
   password: System.fetch_env!("TYPEDB_PASSWORD")}
]

Supervisor.start_link(children, strategy: :one_for_one)

Then query. TypeDB is the default connection name:

TypeDB.query!(TypeDB, "social", """
  match
    $p isa person, has name $name;
  select $name;
""")
|> Enum.map(&TypeDB.ConceptRow.typed_value(&1, "name"))
#=> ["Alice", "Bob"]

The two ways to run a query

query/4 runs a single query in its own transaction — TypeDB opens it, runs the query, and commits or closes it in one round trip. Reads never commit; writes and schema changes commit by default, which commit: false turns off. Every function takes the connection's registered name as its first argument; conn below is that name, TypeDB unless you chose another.

TypeDB.query(conn, "social", "insert $p isa person, has name 'Alice';")

transaction/5 opens a transaction you can run several queries in, committing once at the end:

TypeDB.transaction(conn, "social", :write, fn tx ->
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Alice';")
  TypeDB.Transaction.query!(tx, "insert $p isa person, has name 'Bob';")
end)

The block commits on success and rolls back on error or exception. A :read block never commits.

Answers

Every query returns a TypeDB.Answer — see that module for the three shapes and how to consume them.

Errors

Every function in this module and in TypeDB.Database, TypeDB.User, TypeDB.Server and TypeDB.Transaction that can fail has both a {:ok, _} | {:error, %TypeDB.Error{}} form and a ! form that raises. TypeDB.Error carries TypeDB's own error :code, which is what you want to branch on.

The one exception is transaction/5: it returns whatever your block returned, so its {:error, _} may be your own value rather than an exception, and a bang form would have to guess whether to raise it.

How long a call can take

Four options interact, and only the last of them bounds the call rather than one attempt. With the defaults:

So a retryable call costs at worst

(max_retries + 1) * (connect_timeout + timeout) + max_retries * retry_max_delay

which is a little over two minutes by default, plus one more connect_timeout + timeout if the call has to mint a token first. Raising :max_retries multiplies the first term — that is the arithmetic :deadline exists for, since setting it makes the whole expression irrelevant: no call outlives its budget, each attempt is given only what the budget has left, and a retry that could not finish inside it is not started.

Retries and their backoffs happen in the calling process. Nothing is queued behind a connection, but nothing is running in the caller either.

Logging

The driver logs sparingly, and nothing at all on the happy path — use TypeDB.Telemetry for that. This is everything it can say:

TypeDB.HTTP.Httpc additionally warns once at start-up when it can find no OS trust store, carrying :typedb_adapter rather than :typedb_connection: it happens while the adapter is being built, before there is a connection to name or a :log_level to consult.

Set :log_level on the connection to raise the floor, or :none to silence it — see TypeDB.Config. It applies per connection, so one noisy connection can be quietened without filtering the whole application's Logger by module.

Every line carries :typedb_connection in its Logger metadata, and the retry and give-up lines additionally carry :typedb_method, :typedb_path, :typedb_attempt and :typedb_error_kind. Configure your backend to keep them:

config :logger, :default_formatter,
  metadata: [:typedb_connection, :typedb_error_kind]

Credentials never appear in a log line or in metadata; see TypeDB.Config for how the connection keeps them out of crash reports too.

Concurrency

Requests run in the calling process, so N processes issue N concurrent requests; the connection process is consulted only to mint or renew the auth token. Sockets are pooled by the HTTP adapter — :max_sessions on TypeDB.HTTP.Httpc caps how many are opened per host.

What this driver covers

Everything in the TypeDB HTTP API v1: sign-in and token renewal, databases, users, servers, version and health, explicit transactions, one-shot queries, and query analysis. TypeDB's gRPC-only features — database import/export and streaming answers — are not available over HTTP and so are not here.