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.

What that costs you in practice, and the four other things worth knowing before they surprise you in production, are in the Limitations section of the README: answers arrive whole, a connection points at one server, retries block the caller, and one connection means one HTTP pool.