# `TerminusDB.Database`
[🔗](https://github.com/thanos/terminusdb-client-elixir/blob/v0.3.3/lib/terminus_db/database.ex#L1)

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

# `create_opt`

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

# `delete_opt`

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

# `info_opt`

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

# `create`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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?`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*