Tursox.Database (tursox v0.2.1)

Copy Markdown View Source

Opaque root resource for one local embedded Turso database.

A database is opened once and can derive many independent Tursox.Connection resources. :memory databases are shared by connections derived from the same handle; separate opens remain isolated.

Builder features are experimental upstream and opt-in through :features.

DANGER: unsafe engine features

:unsafe_features enables pinned Turso paths proven capable of terminating the entire BEAM with SIGBUS or SIGSEGV. Use them only when process loss is acceptable. They remain exposed so applications can evaluate cutting-edge behavior without recompiling Tursox.

Summary

Types

t()

Functions

builder_features()

Experimental open-time features available in the pinned Turso build.

close(database)

Logically closes a database. It is safe to call repeatedly.

connect(database, opts \\ [])

Derives an independent connection from this database handle.

encryption_ciphers()

Encryption ciphers compiled into every Tursox build and their raw key sizes.

metadata(database)

Returns safe metadata without exposing the native reference.

open(path, opts \\ [])

Opens a local file or isolated in-memory database.

unsafe_builder_features()

Builder features that may terminate the VM and require explicit acknowledgement.

Types

t()

@opaque t()

Functions

builder_features()

@spec builder_features() :: [atom()]

Experimental open-time features available in the pinned Turso build.

close(database)

@spec close(t()) :: :ok

Logically closes a database. It is safe to call repeatedly.

connect(database, opts \\ [])

@spec connect(
  t(),
  keyword()
) :: {:ok, Tursox.Connection.t()} | {:error, Tursox.Error.t()}

Derives an independent connection from this database handle.

encryption_ciphers()

@spec encryption_ciphers() :: %{required(atom()) => pos_integer()}

Encryption ciphers compiled into every Tursox build and their raw key sizes.

metadata(database)

@spec metadata(t()) :: map()

Returns safe metadata without exposing the native reference.

open(path, opts \\ [])

@spec open(
  :memory | String.t(),
  keyword()
) :: {:ok, t()} | {:error, Tursox.Error.t()}

Opens a local file or isolated in-memory database.

Supported options are:

  • :journal_mode — :wal (default) or experimental :mvcc;
  • :features — an opt-in list from builder_features/0;
  • :unsafe_features — explicit crash-risk opt-ins from unsafe_builder_features/0;
  • :encryption — [cipher: atom, key: binary] when :encryption is enabled;
  • :create_parent — create a missing file parent directory (default false);
  • :mode — only :read_write_create is supported by Turso 0.7.2;
  • :busy_timeout — timeout used while applying/verifying open pragmas.

unsafe_builder_features()

@spec unsafe_builder_features() :: [atom()]

Builder features that may terminate the VM and require explicit acknowledgement.