TerminusDB.Database (terminusdb_ex v0.1.0)

Database management API for TerminusDB.

A database is the top-level container holding a schema, instance data, and a full commit history. This module wraps the /api/db endpoints.

All functions accept a TerminusDB.Config and return {:ok, result} or {:error, TerminusDB.Error.t()}. The !/-suffixed variants raise instead. The organization defaults to config.organization but can be overridden per call via the :organization option.

Examples

config = TerminusDB.Config.new(endpoint: "http://localhost:6363")

{:ok, _} = TerminusDB.Database.create(config, "mydb",
  label: "My Database",
  comment: "A demo database",
  schema: true
)

{:ok, details} = TerminusDB.Database.info(config, "mydb")
true = TerminusDB.Database.exists?(config, "mydb")
:ok = TerminusDB.Database.delete(config, "mydb")

Summary

Types

create_opt()

delete_opt()

info_opt()

Functions

create(config, db_name, opts \\ [])

Creates a new database db_name in the configured (or given) organization.

create!(config, db_name, opts \\ [])

Creates a database, returning the response body or raising TerminusDB.Error.

delete(config, db_name, opts \\ [])

Deletes the database db_name.

delete!(config, db_name, opts \\ [])

Deletes a database, returning the response body or raising TerminusDB.Error.

exists?(config, db_name, opts \\ [])

Returns true if the database db_name exists, false otherwise.

info(config, db_name, opts \\ [])

Returns details for the database db_name (a list of database descriptors).

info!(config, db_name, opts \\ [])

Returns database details, or raises TerminusDB.Error.

list(config, opts \\ [])

Lists all databases available to the authenticated user.

list!(config, opts \\ [])

Lists all databases, or raises TerminusDB.Error.

update(config, db_name, opts \\ [])

Updates metadata (label, comment, etc.) for the database db_name.

update!(config, db_name, opts \\ [])

Updates a database, returning the response body or raising TerminusDB.Error.

Types

create_opt()

@type create_opt() ::
  {:label, String.t()}
  | {:comment, String.t()}
  | {:schema, boolean()}
  | {:public, boolean()}
  | {:prefixes, map()}
  | {:organization, String.t()}

delete_opt()

@type delete_opt() :: {:organization, String.t()} | {:force, boolean()}

info_opt()

@type info_opt() ::
  {:organization, String.t()} | {:branches, boolean()} | {:verbose, boolean()}

Functions

create(config, db_name, opts \\ [])

@spec create(TerminusDB.Config.t(), String.t(), [create_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Creates a new database db_name in the configured (or given) organization.

Options

:label — human-readable name (defaults to db_name).
:comment — description (defaults to "").
:schema — whether to initialize a schema graph (default true).
:public — whether the database is accessible to all users.
:prefixes — custom @base/@schema IRI prefixes.
:organization — overrides config.organization.

Returns {:ok, response_body} on success. The response is a map of the shape %{"@type" => "api:DbCreateResponse", "api:status" => "api:success"}.

Examples

iex> {:ok, _} =
...>   TerminusDB.Database.create(config, "mydb", label: "My DB", schema: true)

create!(config, db_name, opts \\ [])

@spec create!(TerminusDB.Config.t(), String.t(), [create_opt()]) :: map()

Creates a database, returning the response body or raising TerminusDB.Error.

delete(config, db_name, opts \\ [])

@spec delete(TerminusDB.Config.t(), String.t(), [delete_opt()]) ::
  {:ok, map() | nil} | {:error, TerminusDB.Error.t()}

Deletes the database db_name.

Options

:force — force deletion of databases in inconsistent states (default false).
:organization — overrides config.organization.

Examples

iex> :ok = TerminusDB.Database.delete(config, "mydb")
iex> :ok = TerminusDB.Database.delete(config, "mydb", force: true)

delete!(config, db_name, opts \\ [])

@spec delete!(TerminusDB.Config.t(), String.t(), [delete_opt()]) :: map() | nil

Deletes a database, returning the response body or raising TerminusDB.Error.

exists?(config, db_name, opts \\ [])

@spec exists?(TerminusDB.Config.t(), String.t(), [delete_opt()]) :: boolean()

Returns true if the database db_name exists, false otherwise.

Uses HEAD /api/db/:org/:db. A 404 is interpreted as "does not exist"; any other non-success response raises TerminusDB.Error.

Options

:organization — overrides config.organization.

info(config, db_name, opts \\ [])

@spec info(TerminusDB.Config.t(), String.t(), [info_opt()]) ::
  {:ok, [map()]} | {:error, TerminusDB.Error.t()}

Returns details for the database db_name (a list of database descriptors).

Options

:branches — include branch information (default false).
:verbose — return all available information (default false).
:organization — overrides config.organization.

info!(config, db_name, opts \\ [])

@spec info!(TerminusDB.Config.t(), String.t(), [info_opt()]) :: [map()]

Returns database details, or raises TerminusDB.Error.

list(config, opts \\ [])

@spec list(TerminusDB.Config.t(), [info_opt()]) ::
  {:ok, [map()]} | {:error, TerminusDB.Error.t()}

Lists all databases available to the authenticated user.

Options

:branches — include branch information (default false).
:verbose — return all available information (default false).

list!(config, opts \\ [])

@spec list!(TerminusDB.Config.t(), [info_opt()]) :: [map()]

Lists all databases, or raises TerminusDB.Error.

update(config, db_name, opts \\ [])

@spec update(TerminusDB.Config.t(), String.t(), [create_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Updates metadata (label, comment, etc.) for the database db_name.

Accepts the same body options as create/3 (:label, :comment, :schema, :public, :prefixes) plus :organization.

update!(config, db_name, opts \\ [])

@spec update!(TerminusDB.Config.t(), String.t(), [create_opt()]) :: map()

Updates a database, returning the response body or raising TerminusDB.Error.