TerminusDB.Config (terminusdb_ex v0.1.0)

Immutable connection and resource context for a TerminusDB server.

A Config carries everything needed to address and authenticate a request: the server :endpoint, credentials, and the current resource scope (:organization, :database, :branch, :repo, :ref).

Unlike the official Python client — which holds mutable connection state on an instance — TerminusDB.Config is immutable data. Scoping operations return derived configs (with_database/2, with_branch/2, …) rather than mutating, which is safe under concurrency and composes naturally with pipelines.

Options

:endpoint (String.t/0) - Required. TerminusDB server URL, e.g. http://localhost:6363.
:user (String.t/0) - User name for HTTP Basic auth. Ignored when :token is set. The default value is "admin".
:key (String.t/0) - API key / password for HTTP Basic auth. Ignored when :token is set. The default value is "root".
:token (String.t/0) - Bearer token. When set, takes precedence over Basic auth (:user/:key).
:organization (String.t/0) - Organization (team) that owns the database. The default value is "admin".
:database (String.t/0) - Current database name. Set with with_database/2.
:branch (String.t/0) - Current branch. Set with with_branch/2. The default value is "main".
:repo (String.t/0) - Repository: local or a remote name. The default value is "local".
:ref (String.t/0) - A commit reference for time-travel queries.
:headers (map of String.t/0 keys and String.t/0 values) - Extra HTTP headers merged into every request. The default value is %{}.
:receive_timeout (pos_integer/0) - Socket receive timeout in milliseconds. The default value is 15000.
:telemetry (boolean/0) - Whether to emit :telemetry events for operations. The default value is true.
:adapter (term/0) - A Req adapter function used in place of the network. Intended for testing: adapter: fn req -> {req, Req.Response.new(status: 200, body: %{})} end.
:user_agent (String.t/0) - Value of the user-agent request header. The default value is "terminusdb_ex/0.1.0".

Examples

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> config.endpoint
"http://localhost:6363"
iex> config.organization
"admin"

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363", token: "tok_123")
iex> TerminusDB.Config.auth(config)
{:bearer, "tok_123"}

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> TerminusDB.Config.auth(config)
{:basic, "admin:root"}

Summary

Types

auth()

t()

Functions

auth(config)

Returns the Req auth tuple derived from config.

merge(config, opts)

Returns a copy of config with the given fields updated.

new(opts)

Builds a new, validated TerminusDB.Config.

redact(config)

Returns config with sensitive fields redacted, suitable for telemetry metadata and logging. Replaces :key and :token with "[redacted]".

schema()

The NimbleOptions schema used to validate new/1 options.

with_branch(config, branch)

Scopes config to the given branch.

with_database(config, database)

Scopes config to the given database.

with_organization(config, organization)

Scopes config to the given organization.

with_ref(config, ref)

Pins config to a commit reference for time-travel queries.

with_repo(config, repo)

Scopes config to the given repository (local or a remote name).

Types

auth()

@type auth() :: {:basic, String.t()} | {:bearer, String.t()} | nil

t()

@type t() :: %TerminusDB.Config{
  adapter: (Req.Request.t() -> {Req.Request.t(), Req.Response.t()}) | nil,
  branch: String.t(),
  database: String.t() | nil,
  endpoint: String.t(),
  headers: %{required(String.t()) => String.t()},
  key: String.t(),
  organization: String.t(),
  receive_timeout: pos_integer(),
  ref: String.t() | nil,
  repo: String.t(),
  telemetry: boolean(),
  token: String.t() | nil,
  user: String.t(),
  user_agent: String.t()
}

Functions

auth(config)

@spec auth(t()) :: auth()

Returns the Req auth tuple derived from config.

A :token takes precedence (Bearer); otherwise Basic auth is built from :user and :key. Returns nil only if no credentials are usable.

Examples

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363", token: "abc")
iex> TerminusDB.Config.auth(config)
{:bearer, "abc"}

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363", user: "admin", key: "root")
iex> TerminusDB.Config.auth(config)
{:basic, "admin:root"}

merge(config, opts)

@spec merge(
  t(),
  keyword()
) :: t()

Returns a copy of config with the given fields updated.

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> TerminusDB.Config.merge(config, database: "mydb").database
"mydb"

new(opts)

@spec new(keyword()) :: t()

Builds a new, validated TerminusDB.Config.

Options

See the module documentation or schema/0 for the accepted options.

Examples

iex> %TerminusDB.Config{endpoint: "http://localhost:6363"} =
...>   TerminusDB.Config.new(endpoint: "http://localhost:6363")

iex> TerminusDB.Config.new(endpoint: "http://localhost:6363", database: "foo").database
"foo"

Raises NimbleOptions.ValidationError on invalid options.

iex> TerminusDB.Config.new(endpoint: 123)
** (NimbleOptions.ValidationError) invalid value for :endpoint option: expected string, got: 123

redact(config)

@spec redact(t()) :: t()

Returns config with sensitive fields redacted, suitable for telemetry metadata and logging. Replaces :key and :token with "[redacted]".

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363", key: "secret")
iex> redacted = TerminusDB.Config.redact(config)
iex> redacted.key
"[redacted]"
iex> redacted.endpoint
"http://localhost:6363"

schema()

@spec schema() :: keyword()

The NimbleOptions schema used to validate new/1 options.

with_branch(config, branch)

@spec with_branch(t(), String.t()) :: t()

Scopes config to the given branch.

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> TerminusDB.Config.with_branch(config, "feature").branch
"feature"

with_database(config, database)

@spec with_database(t(), String.t()) :: t()

Scopes config to the given database.

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> TerminusDB.Config.with_database(config, "mydb").database
"mydb"

with_organization(config, organization)

@spec with_organization(t(), String.t()) :: t()

Scopes config to the given organization.

iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
iex> TerminusDB.Config.with_organization(config, "acme").organization
"acme"

with_ref(config, ref)

@spec with_ref(t(), String.t()) :: t()

Pins config to a commit reference for time-travel queries.

with_repo(config, repo)

@spec with_repo(t(), String.t()) :: t()

Scopes config to the given repository (local or a remote name).