ExSQL.Connection (exsql v0.1.1)

Copy Markdown

A stateful database handle, holding an ExSQL.Database value in a GenServer.

This is the process-shaped counterpart to a sqlite3* connection pointer: statements from any process are serialized through the server, which is the BEAM-native answer to SQLite's connection mutex. The functional core stays pure — this module only threads the database value through ExSQL.Executor.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

create_aggregate(conn, name, arity, callback)

Registers or replaces a connection-local aggregate function.

create_collation(conn, name, callback)

Registers or replaces a connection-local collation.

create_function(conn, name, arity, callback)

Registers or replaces a connection-local scalar function.

create_incremental_window_function(conn, name, arity, callbacks)

Registers or replaces a connection-local incremental aggregate window function.

create_window_function(conn, name, arity, callback)

Registers or replaces a connection-local aggregate window function.

database(conn)

Returns a snapshot of the current database value.

execute(conn, sql, params \\ [])

Executes all statements in sql, returning {:ok, results} with one ExSQL.Result per statement. On error, statements before the failure have taken effect (as with sqlite3_exec).

read(conn_or_snapshot, sql, params \\ [])

Runs a read-only query against a snapshot in the calling process, so it executes concurrently with — and without blocking — the connection's other work. Accepts either a snapshot from snapshot/1 or a connection (which is snapshotted first).

snapshot(conn)

Captures a consistent point-in-time snapshot of the database.

start_link(opts \\ [])

Starts a connection holding an empty database.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

create_aggregate(conn, name, arity, callback)

@spec create_aggregate(GenServer.server(), String.t(), non_neg_integer(), function()) ::
  :ok | {:error, ExSQL.Error.t()}

Registers or replaces a connection-local aggregate function.

create_collation(conn, name, callback)

@spec create_collation(GenServer.server(), String.t(), function()) ::
  :ok | {:error, ExSQL.Error.t()}

Registers or replaces a connection-local collation.

create_function(conn, name, arity, callback)

@spec create_function(GenServer.server(), String.t(), non_neg_integer(), function()) ::
  :ok | {:error, ExSQL.Error.t()}

Registers or replaces a connection-local scalar function.

create_incremental_window_function(conn, name, arity, callbacks)

@spec create_incremental_window_function(
  GenServer.server(),
  String.t(),
  non_neg_integer(),
  map()
) :: :ok | {:error, ExSQL.Error.t()}

Registers or replaces a connection-local incremental aggregate window function.

create_window_function(conn, name, arity, callback)

@spec create_window_function(
  GenServer.server(),
  String.t(),
  non_neg_integer(),
  function()
) ::
  :ok | {:error, ExSQL.Error.t()}

Registers or replaces a connection-local aggregate window function.

database(conn)

@spec database(GenServer.server()) :: ExSQL.Database.t()

Returns a snapshot of the current database value.

execute(conn, sql, params \\ [])

@spec execute(GenServer.server(), String.t(), [ExSQL.Value.t()] | map()) ::
  {:ok, [ExSQL.Result.t()]} | {:error, ExSQL.Error.t()}

Executes all statements in sql, returning {:ok, results} with one ExSQL.Result per statement. On error, statements before the failure have taken effect (as with sqlite3_exec).

Bind parameters (?, ?NNN, :name, @name, $name) are bound from params: a list for positional parameters (1-based) or a map for named ones (keys may include or omit the sigil; integer keys bind by index).

read(conn_or_snapshot, sql, params \\ [])

@spec read(
  GenServer.server() | ExSQL.Database.t(),
  String.t(),
  [ExSQL.Value.t()] | map()
) ::
  {:ok, [ExSQL.Result.t()]} | {:error, ExSQL.Error.t()}

Runs a read-only query against a snapshot in the calling process, so it executes concurrently with — and without blocking — the connection's other work. Accepts either a snapshot from snapshot/1 or a connection (which is snapshotted first).

Because the snapshot is immutable, the read is isolated and consistent. Any statement that would modify the database has no persistent effect (the connection's state is untouched); read/3 is for SELECT-style queries.

snapshot(conn)

@spec snapshot(GenServer.server()) :: ExSQL.Database.t()

Captures a consistent point-in-time snapshot of the database.

The result is an immutable ExSQL.Database value. Reads run against it with read/3 see that exact point in time and are unaffected by writes committed afterwards — the BEAM-native equivalent of a SQLite WAL read transaction / sqlite3_snapshot.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts a connection holding an empty database.