TerminusDB.Database (terminusdb_ex v0.3.3)

Copy Markdown View Source

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.

optimize(config, path)

Optimizes a resource path (branch, _meta, or _commits graph).

optimize!(config, path)

Optimizes a resource path, or raises.

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> TerminusDB.Database.create!(config, "mydb", label: "My DB")
%{"api:status" => "api:success"}

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> TerminusDB.Database.delete!(config, "mydb")
%{"api:status" => "api:success"}

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: "")} end
...> )
iex> TerminusDB.Database.exists?(config, "mydb")
true

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 404, body: "")} end
...> )
iex> TerminusDB.Database.exists?(config, "missing")
false

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: [%{"name" => "mydb", "@type" => "UserDatabase"}])} end
...> )
iex> {:ok, details} = TerminusDB.Database.info(config, "mydb")
iex> hd(details)["name"]
"mydb"

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

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

Returns database details, or raises TerminusDB.Error.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: [%{"name" => "mydb"}])} end
...> )
iex> TerminusDB.Database.info!(config, "mydb")
[%{"name" => "mydb"}]

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).

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: [%{"name" => "a"}, %{"name" => "b"}])} end
...> )
iex> {:ok, dbs} = TerminusDB.Database.list(config)
iex> Enum.map(dbs, & &1["name"])
["a", "b"]

list!(config, opts \\ [])

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

Lists all databases, or raises TerminusDB.Error.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: [%{"name" => "mydb"}])} end
...> )
iex> TerminusDB.Database.list!(config)
[%{"name" => "mydb"}]

optimize(config, path)

@spec optimize(TerminusDB.Config.t(), String.t()) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}

Optimizes a resource path (branch, _meta, or _commits graph).

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> ) |> TerminusDB.Config.with_database("mydb")
iex> {:ok, resp} = TerminusDB.Database.optimize(config, "admin/mydb/local/branch/main")
iex> resp["api:status"]
"api:success"

optimize!(config, path)

@spec optimize!(TerminusDB.Config.t(), String.t()) :: map()

Optimizes a resource path, or raises.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> TerminusDB.Database.optimize!(config, "_system")
%{"api:status" => "api:success"}

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> {:ok, resp} = TerminusDB.Database.update(config, "mydb", label: "New Label")
iex> resp["api:status"]
"api:success"

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.

Examples

iex> config = TerminusDB.Config.new(
...>   endpoint: "http://localhost:6363",
...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> TerminusDB.Database.update!(config, "mydb", label: "New Label")
%{"api:status" => "api:success"}