Arcadic.Server (Arcadic v0.7.0)

Copy Markdown View Source

Server-level admin: create/drop/list databases, existence, readiness. Every identifier is allowlist-validated BEFORE any request reaches the wire (fixes the interpolation surface a hand-written create database <name> would open). Returns are tagged tuples — a transport failure is never swallowed into a bare boolean. Not delegated from the Arcadic facade: destructive admin stays namespaced.

Summary

Functions

align_database(conn, name)

Cluster-realign a database. CLUSTER-ONLY — a single-server node returns a server error (java.lang.UnsupportedOperationException, surfaced as {:error, %Arcadic.Error{reason: :server_error}}). Validates name.

align_database!(conn, name)
check_database(conn, opts \\ [])

Run CHECK DATABASE [FIX] on conn.database. fix: true repairs. Returns the integrity map.

check_database!(conn, opts \\ [])
close_database(conn, name)

Close an open database on the server. Validates name.

close_database!(conn, name)
create_database(conn, name)

Create a database. Validates name.

create_database!(conn, name)

Create a database, raising on error.

database_exists?(conn, name)

Whether a database exists.

database_info(conn)

Database-level info for conn.database — %{database, type, records, classes, size_bytes}. Fields a transport can't cheaply provide are nil (HTTP gives name/size; gRPC gives all). :not_supported on a transport without the callback (e.g. Bolt).

drop_database(conn, name)

Drop a database. Validates name.

drop_database!(conn, name)

Drop a database, raising on error.

events(conn)

Server event log map (%{"events" => [...], "files" => [...]}).

events!(conn)
health?(conn)

Liveness probe (GET /api/v1/health → 204).

info(conn, opts \\ [])

Server info map. :mode ∈ [:basic, :default, :cluster] (default :basic); :default/:cluster add metrics/settings.

info!(conn, opts \\ [])
list_databases(conn)

List all databases.

metrics(conn)

The server metrics map (info(conn, mode: :default)["metrics"]).

metrics!(conn)
open_database(conn, name)

Open a closed database on the server. Validates name.

open_database!(conn, name)
profiler(conn, action)

Control the server profiler. action ∈ [:results, :start, :stop, :reset].

profiler!(conn, action)
ready?(conn)

Server readiness.

set_database_setting(conn, key, value)

Set a setting on conn.database (set database setting <db> `k` `v`). Guards as set_server_setting/3.

set_database_setting!(conn, key, value)
set_server_setting(conn, key, value)

Set a server-level setting (set server setting `k` `v`). key is allowlist-validated (dotted); value must not contain a backtick, backslash, or control character (the backtick-quoting and escape context) — non-ASCII printable values are allowed. Both are rejected value-free ({:error, :invalid_setting_key | :invalid_setting_value}).

set_server_setting!(conn, key, value)
shutdown(conn)

Shut the server down (shutdown). DESTRUCTIVE — halts shared infrastructure. The server stops responding mid-request, so a SUCCESSFUL shutdown typically surfaces as {:error, %Arcadic.TransportError{reason: :closed}} (connection reset), not :ok — treat a transport-closed error here as success, not a retryable failure.

shutdown!(conn)

Functions

align_database(conn, name)

@spec align_database(Arcadic.Conn.t(), String.t()) ::
  {:ok, map()} | {:error, atom() | Exception.t()}

Cluster-realign a database. CLUSTER-ONLY — a single-server node returns a server error (java.lang.UnsupportedOperationException, surfaced as {:error, %Arcadic.Error{reason: :server_error}}). Validates name.

align_database!(conn, name)

@spec align_database!(Arcadic.Conn.t(), String.t()) :: map()

check_database(conn, opts \\ [])

@spec check_database(
  Arcadic.Conn.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}

Run CHECK DATABASE [FIX] on conn.database. fix: true repairs. Returns the integrity map.

check_database!(conn, opts \\ [])

@spec check_database!(
  Arcadic.Conn.t(),
  keyword()
) :: map()

close_database(conn, name)

@spec close_database(Arcadic.Conn.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Close an open database on the server. Validates name.

close_database!(conn, name)

@spec close_database!(Arcadic.Conn.t(), String.t()) :: :ok

create_database(conn, name)

@spec create_database(Arcadic.Conn.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Create a database. Validates name.

create_database!(conn, name)

@spec create_database!(Arcadic.Conn.t(), String.t()) :: :ok

Create a database, raising on error.

database_exists?(conn, name)

@spec database_exists?(Arcadic.Conn.t(), String.t()) ::
  {:ok, boolean()} | {:error, atom() | Exception.t()}

Whether a database exists.

database_info(conn)

@spec database_info(Arcadic.Conn.t()) ::
  {:ok, map()} | {:error, atom() | Exception.t()}

Database-level info for conn.database — %{database, type, records, classes, size_bytes}. Fields a transport can't cheaply provide are nil (HTTP gives name/size; gRPC gives all). :not_supported on a transport without the callback (e.g. Bolt).

drop_database(conn, name)

@spec drop_database(Arcadic.Conn.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Drop a database. Validates name.

drop_database!(conn, name)

@spec drop_database!(Arcadic.Conn.t(), String.t()) :: :ok

Drop a database, raising on error.

events(conn)

@spec events(Arcadic.Conn.t()) :: {:ok, map()} | {:error, Exception.t()}

Server event log map (%{"events" => [...], "files" => [...]}).

events!(conn)

@spec events!(Arcadic.Conn.t()) :: map()

health?(conn)

@spec health?(Arcadic.Conn.t()) :: {:ok, boolean()} | {:error, Exception.t()}

Liveness probe (GET /api/v1/health → 204).

info(conn, opts \\ [])

@spec info(
  Arcadic.Conn.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}

Server info map. :mode ∈ [:basic, :default, :cluster] (default :basic); :default/:cluster add metrics/settings.

info!(conn, opts \\ [])

@spec info!(
  Arcadic.Conn.t(),
  keyword()
) :: map()

list_databases(conn)

@spec list_databases(Arcadic.Conn.t()) ::
  {:ok, [String.t()]} | {:error, Exception.t()}

List all databases.

metrics(conn)

@spec metrics(Arcadic.Conn.t()) :: {:ok, map()} | {:error, Exception.t()}

The server metrics map (info(conn, mode: :default)["metrics"]).

metrics!(conn)

@spec metrics!(Arcadic.Conn.t()) :: map()

open_database(conn, name)

@spec open_database(Arcadic.Conn.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Open a closed database on the server. Validates name.

open_database!(conn, name)

@spec open_database!(Arcadic.Conn.t(), String.t()) :: :ok

profiler(conn, action)

@spec profiler(Arcadic.Conn.t(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Control the server profiler. action ∈ [:results, :start, :stop, :reset].

profiler!(conn, action)

@spec profiler!(Arcadic.Conn.t(), atom()) :: map()

ready?(conn)

@spec ready?(Arcadic.Conn.t()) :: {:ok, boolean()} | {:error, Exception.t()}

Server readiness.

set_database_setting(conn, key, value)

@spec set_database_setting(Arcadic.Conn.t(), String.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Set a setting on conn.database (set database setting <db> `k` `v`). Guards as set_server_setting/3.

set_database_setting!(conn, key, value)

@spec set_database_setting!(Arcadic.Conn.t(), String.t(), String.t()) :: :ok

set_server_setting(conn, key, value)

@spec set_server_setting(Arcadic.Conn.t(), String.t(), String.t()) ::
  :ok | {:error, atom() | Exception.t()}

Set a server-level setting (set server setting `k` `v`). key is allowlist-validated (dotted); value must not contain a backtick, backslash, or control character (the backtick-quoting and escape context) — non-ASCII printable values are allowed. Both are rejected value-free ({:error, :invalid_setting_key | :invalid_setting_value}).

set_server_setting!(conn, key, value)

@spec set_server_setting!(Arcadic.Conn.t(), String.t(), String.t()) :: :ok

shutdown(conn)

@spec shutdown(Arcadic.Conn.t()) :: :ok | {:error, Exception.t()}

Shut the server down (shutdown). DESTRUCTIVE — halts shared infrastructure. The server stops responding mid-request, so a SUCCESSFUL shutdown typically surfaces as {:error, %Arcadic.TransportError{reason: :closed}} (connection reset), not :ok — treat a transport-closed error here as success, not a retryable failure.

shutdown!(conn)

@spec shutdown!(Arcadic.Conn.t()) :: :ok