@spec autocommit(conn()) :: {:ok, boolean()} | error()

Returns {:ok, true} when the connection is in auto-commit mode (no active transaction), {:ok, false} otherwise.

The inverse view of transaction_status/1, matching SQLite's sqlite3_get_autocommit. Wraps XqliteNIF.autocommit/1. No telemetry is emitted.

@spec backup(conn(), String.t(), String.t()) :: :ok | error()

Backs up a schema to a file.

Copies the named schema (default "main") to the file at dest_path. The destination is created or overwritten. The source remains readable during the backup.

@spec backup_with_progress(
  conn(),
  String.t(),
  String.t(),
  pid(),
  pos_integer(),
  reference() | [reference()]
) :: :ok | error()

Online backup with progress messages and cancellation. Accepts either a single cancel token or a list (OR-semantics).

Sends {:xqlite_backup_progress, remaining, pagecount} to pid after each pages_per_step-page step. Returns {:error, :operation_cancelled} if any token signals between steps.

pages_per_step must be a positive integer. A non-positive value returns {:error, {:invalid_pages_per_step, value}} — passing 0 would otherwise make SQLite copy no pages while reporting "more", spinning forever.

@spec begin(conn(), :deferred | :immediate | :exclusive) :: :ok | error()

Begins a transaction in the given mode (:deferred, :immediate, or :exclusive). Emits [:xqlite, :transaction, :begin] telemetry.

@spec bind(stmt(), list()) :: :ok | error()

Binds parameters to a prepared statement.

Accepts a plain list for positional placeholders (?1, ?2, …; the count must match, otherwise {:error, {:invalid_parameter_count, %{provided: _, expected: _}}}) or a keyword list for named placeholders. Once stepping has started, call reset/1 before rebinding — SQLite rejects mid-run rebinds.

@spec busy_timeout(conn(), non_neg_integer()) :: :ok | error()

Sets a plain sqlite3_busy_timeout on the connection, replacing the xqlite busy slot cleanly.

Calls remove_busy_policy/1 first, then sets PRAGMA busy_timeout = ms. Note that the raw PRAGMA replaces the whole C callback: any registered busy observers stop receiving {:xqlite_busy, …} messages too — unregister them first if you want their state reclaimed eagerly rather than at connection close.

Prefer this helper over reaching for PRAGMA busy_timeout directly: the raw PRAGMA silently replaces the callback at the SQLite level without clearing our internal slot. This function keeps both sides consistent.

ms is the timeout in milliseconds. 0 disables the timeout entirely (SQLite returns SQLITE_BUSY immediately on contention).

@spec cancel_operation(reference()) :: :ok | error()

Signals a cancellation token. Emits [:xqlite, :cancel, :signalled].

Idempotent at the SQLite level — signalling twice is the same as once. Telemetry fires on every call, so consumers see distinct signal events even from repeated signals.

@spec changes(conn()) :: {:ok, non_neg_integer()} | error()

Returns the number of rows changed by the most recently completed INSERT, UPDATE, or DELETE on this connection.

The counter is sticky: non-DML statements (SELECT, DDL, PRAGMA) leave it untouched, so it reports the last DML's count rather than resetting to 0. For an atomically captured count prefer query/4 or execute/4, whose Xqlite.Result.t/0 carries changes taken inside the connection lock. Wraps XqliteNIF.changes/1. No telemetry is emitted.

@spec check_strict_violations(conn(), String.t()) :: {:ok, [map()]} | error()

Checks an existing table for values that would violate STRICT typing rules.

Returns {:ok, []} if the table is clean, or {:ok, violations} where each violation is a map with :rowid, :column, :actual_type, and :expected_type.

This is a read-only check — it does not modify the table.

@spec clear_bindings(stmt()) :: :ok | error()

Clears all parameter bindings on a prepared statement back to NULL.

@spec close(conn()) :: :ok

Closes the connection, releasing the underlying SQLite handle.

Idempotent: closing an already-closed connection returns :ok. Any operation on a closed connection returns {:error, :connection_closed}.

Finalize outstanding prepared statements before closing — a connection closed while statements are outstanding keeps the underlying SQLite handle alive until the owning process exits (see prepare/2).

Emits [:xqlite, :close, :start | :stop] telemetry.

@spec column_names(stmt()) :: {:ok, [String.t()]} | error()

Returns the result column names of a prepared statement.

Live statements reflect SQLite's auto-reprepare after schema changes (e.g. SELECT * re-expansion); finalized statements answer with the prepare-time snapshot.

@spec commit(conn()) :: :ok | error()

Commits the current transaction. Emits [:xqlite, :transaction, :commit].

@spec compile_options(conn()) :: {:ok, [String.t()]} | error()

Returns the compile-time options the linked SQLite library was built with, as a list of strings (PRAGMA compile_options).

Useful to confirm features such as ENABLE_FTS5 are present. Wraps XqliteNIF.compile_options/1. No telemetry is emitted.

@spec connection_stats(conn()) :: {:ok, map()} | error()

Returns a snapshot of the connection's sqlite3_db_status counters (lookaside, pager cache, schema and statement memory, cache hit/miss/spill, deferred foreign keys).

See XqliteNIF.connection_stats/1 for the full key list. Call repeatedly for time-series monitoring. No telemetry is emitted.

@spec create_cancel_token() :: {:ok, reference()} | error()

Creates a cancellation token. Emits [:xqlite, :cancel, :token_created].

The token is an opaque reference passed into cancellable operations (query_cancellable/4, execute_cancellable/4, etc.). Signalling it via cancel_operation/1 from any process interrupts in-flight cancellable operations holding the same token.

@spec db_path(conn()) :: {:ok, String.t() | nil} | error()

Returns the filesystem path of the connection's main database.

{:ok, path} for file-backed databases, {:ok, nil} for in-memory and temporary databases (they have no backing file). No telemetry is emitted.

@spec deserialize(conn(), binary(), String.t(), boolean()) :: :ok | error()

Deserializes a binary into a database, replacing its current contents.

The binary must be a valid SQLite database image (as produced by serialize/2). After deserialization the connection operates on the new database entirely in memory.

schema identifies which attached database to replace (default "main"). read_only marks the deserialized image as read-only (default false).

@spec disable_foreign_key_enforcement(conn()) :: {:ok, term()} | error()

Disables foreign key constraint enforcement for the given database connection (default behavior).

See enable_foreign_key_enforcement/1 for details.

@spec disable_strict_mode(conn()) :: {:ok, term()} | error()

Disables strict mode only for the lifetime given database connection (SQLite's default).

See enable_strict_mode/1 for details.

@spec enable_foreign_key_enforcement(conn()) :: {:ok, term()} | error()

Enables foreign key constraint enforcement for the given database connection.

By default, SQLite parses foreign key constraints but does not enforce them. This function turns on enforcement.

See: SQLite PRAGMA foreign_keys

@spec enable_load_extension(conn(), boolean()) :: :ok | error()

Enables or disables extension loading on the connection.

Defaults to true. Wraps XqliteNIF.enable_load_extension/2 and emits [:xqlite, :extension, :enable] telemetry.

@spec enable_strict_mode(conn()) :: {:ok, term()} | error()

Enables strict mode only for the lifetime of the given database connection.

In strict mode, SQLite is less forgiving. For example, an attempt to insert a string into an INTEGER column of a STRICT table will result in an error, whereas in normal mode it might be coerced or stored as text. This setting only affects tables declared with the STRICT keyword.

See: STRICT Tables

@spec enable_strict_table(conn(), String.t()) :: :ok | {:error, term()}

Converts an existing table to STRICT mode via table rebuild.

This creates a new STRICT table, copies all data, drops the original, and renames the new table — all inside a transaction.

If existing data violates STRICT typing rules, the operation fails with {:error, {:strict_violations, violations}} where violations is a list of maps from check_strict_violations/2. The original table is left untouched.

Options

None currently.

Examples

:ok = Xqlite.enable_strict_table(conn, "users")

@spec execute(conn(), String.t(), list() | keyword(), keyword()) ::
  {:ok, Xqlite.Result.t()} | error()

Executes a non-returning SQL statement and returns a %Xqlite.Result{}.

For DML statements, changes contains the number of affected rows.

Options

• :type_extensions — a list of Xqlite.TypeExtension modules; parameters are encoded through the chain before binding (there are no result rows to decode). Default: [].

@spec execute_batch(conn(), String.t()) :: :ok | error()

Executes a SQL batch (multiple statements separated by semicolons).

Wraps XqliteNIF.execute_batch/2 and emits [:xqlite, :execute_batch, :*] telemetry. No parameter binding inside the batch.

@spec execute_batch_cancellable(conn(), String.t(), reference() | [reference()]) ::
  :ok | error()

Cancellable execute_batch/2. Accepts either a single cancel token or a list.

@spec execute_cancellable(
  conn(),
  String.t(),
  list(),
  reference() | [reference()]
) :: {:ok, non_neg_integer()} | error()

Cancellable execute/3. Accepts either a single cancel token or a list.

@spec explain_analyze(conn(), String.t(), list() | keyword()) ::
  {:ok, Xqlite.ExplainAnalyze.t()} | error()

Runs a SQL statement and returns an %Xqlite.ExplainAnalyze{} report.

The statement is executed in full (rows are fetched and discarded). The returned struct combines the static EXPLAIN QUERY PLAN tree with runtime counters from sqlite3_stmt_scanstatus_v2 / sqlite3_stmt_status and a wall-clock measurement around the execution. See Xqlite.ExplainAnalyze for the field layout and how to interpret it.

Examples

iex> {:ok, conn} = Xqlite.open_in_memory()
iex> XqliteNIF.execute_batch(conn, "CREATE TABLE t(id INTEGER PRIMARY KEY, name TEXT); INSERT INTO t(name) VALUES ('a'), ('b');")
:ok
iex> {:ok, report} = Xqlite.explain_analyze(conn, "SELECT name FROM t WHERE name = ?", ["b"])
iex> match?(%Xqlite.ExplainAnalyze{}, report)
true

@spec finalize(stmt()) :: :ok | error()

Finalizes a prepared statement, releasing its SQLite resources.

Idempotent — repeated finalization returns :ok. Prefer explicit finalization over relying on garbage collection, and finalize before closing the owning connection (see prepare/2).

@spec get_create_sql(conn(), String.t()) :: {:ok, String.t() | nil} | error()

Returns the CREATE ... SQL for a schema object as recorded in sqlite_schema, or {:ok, nil} when no object with that name exists.

Wraps XqliteNIF.get_create_sql/2. No telemetry is emitted.

@spec get_pragma(conn(), String.t() | atom()) :: {:ok, term()} | error()

Reads a PRAGMA value from the connection.

Wraps XqliteNIF.get_pragma/2 and emits [:xqlite, :pragma, :get].

@spec last_insert_rowid(conn()) :: {:ok, integer()} | error()

Returns the rowid of the most recent successful INSERT on this connection.

Connection-specific and only updated by successful INSERTs. Does not work for WITHOUT ROWID tables — use INSERT ... RETURNING there. Wraps XqliteNIF.last_insert_rowid/1. No telemetry is emitted.

@spec load_extension(conn(), String.t(), String.t() | nil) :: :ok | error()

Loads a SQLite extension from the shared library at path.

entry_point is the extension's init function name; pass nil (default) to let SQLite auto-detect. Extension loading must be enabled first via enable_load_extension/2.

@spec multi_step(stmt(), pos_integer()) ::
  {:ok, %{rows: [[sqlite_value()]], done: boolean()}} | error()

Advances a prepared statement up to batch_size rows.

Returns {:ok, %{rows: rows, done: done?}} — done: true means the statement exhausted within this batch (fewer than batch_size rows may be returned in that case) — or {:error, reason}.

Calling again after done: true without a reset/1 RERUNS the query from the top (v2-prepared statements auto-reset when stepped past done — SQLite semantics, same as step/1).

@spec multi_step_cancellable(stmt(), pos_integer(), reference() | [reference()]) ::
  {:ok, %{rows: [[sqlite_value()]], done: boolean()}} | error()

Like multi_step/2 but cancellable.

Accepts a single cancel token or a list (OR-semantics — any signalled token aborts with {:error, :operation_cancelled}). Cancellation rides the connection's progress handler, exactly like query_cancellable/4. After a cancellation, reset/1 the statement before stepping it again.

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

Opens a database connection with opinionated defaults and validated options.

All PRAGMAs are applied on the same connection immediately after opening, with no window for another process to observe an unconfigured state.

Options

• :journal_mode - SQLite journal mode. :wal enables concurrent readers with a single writer. The default value is :wal.

• :busy_timeout (timeout/0) - Milliseconds to wait when the database is locked. :infinity waits forever. The default value is 5000.

• :foreign_keys (boolean/0) - Enable foreign key constraint enforcement. SQLite defaults to OFF. The default value is true.

• :synchronous - Synchronous mode. :normal is safe with WAL and significantly faster than :full. The default value is :normal.

• :cache_size (integer/0) - Page cache size. Negative values mean KB (e.g., -64000 = 64MB). SQLite default is 2MB. The default value is -64000.

• :temp_store - Where to store temporary tables and indices. The default value is :memory.

• :wal_autocheckpoint (non_neg_integer/0) - WAL auto-checkpoint threshold in pages. 0 disables auto-checkpoint. The default value is 1000.

• :mmap_size (non_neg_integer/0) - Memory-mapped I/O size in bytes. 0 disables mmap. The default value is 0.

• :auto_vacuum - Auto-vacuum mode. Must be set before creating any tables. The default value is :none.

Examples

{:ok, conn} = Xqlite.open("my.db")
{:ok, conn} = Xqlite.open("my.db", journal_mode: :delete, busy_timeout: 10_000)

@spec open_in_memory(keyword()) :: {:ok, conn()} | error()

Opens an in-memory database with opinionated defaults and validated options.

Accepts the same options as open/2.

@spec open_in_memory_readonly(String.t()) :: {:ok, conn()} | error()

Opens a read-only connection to an in-memory SQLite database.

Useful for connecting to a named shared-cache in-memory database opened read-write by another connection — pass its URI as uri, or omit it to open a private (empty) read-only :memory: database.

No PRAGMAs are applied; read-only databases can't persist most settings.

@spec open_readonly(String.t()) :: {:ok, conn()} | error()

Opens a read-only connection to an existing database file.

Fails with a structured error if the file does not exist — read-only opens never create. No PRAGMAs are applied; read-only databases can't persist most settings. Writes fail with {:error, {:read_only_database, extended_code, message}}.

Emits [:xqlite, :open, :start | :stop] telemetry with mode :readonly.

@spec open_temporary() :: {:ok, conn()} | error()

Opens a connection to a private temporary on-disk database.

SQLite backs it with an anonymous file it removes on close; the database has no path — db_path/1 returns {:ok, nil}.

Emits [:xqlite, :open, :start | :stop] telemetry with mode :temp and path: nil.

@spec prepare(conn(), String.t()) :: {:ok, stmt()} | error()

Prepares a manually managed statement.

The lifecycle is prepare/2 → (bind/2 → step/1 / multi_step/2 → reset/1)* → finalize/1. Preparing once and rebinding in a loop skips SQL parsing/planning on every iteration — the reason prepared statements exist. For one-shot calls, query/3 and execute/3 remain simpler.

Exactly ONE statement is compiled: whitespace/comment-only SQL returns {:error, {:cannot_execute, reason}} and trailing statements after the first return {:error, :multiple_statements} — nothing is silently dropped.

Finalize statements before closing their connection: a connection closed while statements are outstanding keeps the underlying SQLite handle alive until the process exits (abandoned statements are still finalized by garbage collection, and every operation on them after an explicit Xqlite.close/1 returns {:error, :connection_closed}).

Steps are not cancellable; for cancellation use query_cancellable/4 and friends. No telemetry is emitted for statement-lifecycle operations.

Examples

iex> {:ok, conn} = Xqlite.open_in_memory()
iex> {:ok, 0} = XqliteNIF.execute(conn, "CREATE TABLE pairs (a INTEGER, b TEXT)", [])
iex> {:ok, stmt} = Xqlite.prepare(conn, "INSERT INTO pairs (a, b) VALUES (?1, ?2)")
iex> for {a, b} <- [{1, "one"}, {2, "two"}] do
...>   :ok = Xqlite.bind(stmt, [a, b])
...>   :done = Xqlite.step(stmt)
...>   :ok = Xqlite.reset(stmt)
...> end
[:ok, :ok]
iex> Xqlite.finalize(stmt)
:ok
iex> {:ok, query} = Xqlite.prepare(conn, "SELECT a, b FROM pairs ORDER BY a")
iex> Xqlite.step(query)
{:row, [1, "one"]}
iex> Xqlite.multi_step(query, 10)
{:ok, %{rows: [[2, "two"]], done: true}}
iex> Xqlite.column_names(query)
{:ok, ["a", "b"]}
iex> Xqlite.finalize(query)
:ok

@spec query(conn(), String.t(), list() | keyword(), keyword()) ::
  {:ok, Xqlite.Result.t()} | error()

Executes a SQL query and returns a %Xqlite.Result{} struct.

For SELECT queries, num_rows is the count of returned rows and changes is 0. For DML (INSERT/UPDATE/DELETE), num_rows is 0 (no result rows) and changes is the number of affected rows.

Uses XqliteNIF.query_with_changes/3 which captures the affected row count atomically inside the connection lock. For zero-overhead access without the changes field, use XqliteNIF.query/3 directly.

Options

• :type_extensions — a list of Xqlite.TypeExtension modules. Parameters are encoded through the chain before binding and result rows are decoded through it after fetching (first match wins, same semantics as stream/4). Default: [] (values pass through untouched).

@spec query_cancellable(
  conn(),
  String.t(),
  list() | keyword(),
  reference() | [reference()]
) :: {:ok, query_result()} | error()

Cancellable query/3. Accepts either a single cancel token or a list of tokens; OR-semantics — any signalled token interrupts the query.

See XqliteNIF.query_cancellable/4 for the raw NIF (list form only).

@spec query_with_changes_cancellable(
  conn(),
  String.t(),
  list() | keyword(),
  reference() | [reference()]
) :: {:ok, map()} | error()

Cancellable query_with_changes/3. Accepts either a single cancel token or a list.

@spec register_busy_observer(conn(), pid()) :: {:ok, non_neg_integer()} | error()

Registers a busy-contention observer on the connection.

Every SQLITE_BUSY callback invocation sends

{:xqlite_busy, retries_so_far, elapsed_ms}

to pid. Any number of observers can be registered — each gets its own handle for unregister_busy_observer/2 — and they fire whether or not a retry policy is installed. Xqlite.Telemetry.bridge/2 can subscribe with hooks: [:busy] to re-emit deliveries as [:xqlite, :hook, :busy] telemetry.

@spec register_progress_hook(conn(), pid(), keyword()) ::
  {:ok, non_neg_integer()} | error()

Registers a progress-tick subscriber on the connection.

After every ~64 SQLite VM instructions × every_n, sends

{:xqlite_progress, count, elapsed_ms}              # tag = nil
{:xqlite_progress, tag, count, elapsed_ms}         # tag set

to pid. count is the per-subscriber decimated counter; elapsed_ms is the wall time since this specific subscriber was registered.

Multiple subscribers can coexist independently — each gets its own opaque handle, and unregistering one never affects another.

Options

• :every_n (positive integer, default 1000) — emit every Nth progress callback fire. The progress callback fires every 8 SQLite VM instructions (currently fixed); every_n decimates further.
• :tag (atom, default nil) — included in each emitted message as the second tuple element when set. Useful when a single listener process subscribes to multiple connections and needs to tell them apart without spawning a process per connection.

Returns {:ok, handle} where handle is the value to pass to unregister_progress_hook/2. Returns {:error, reason} on failure.

@spec release_savepoint(conn(), String.t()) :: :ok | error()

Releases a savepoint. Emits [:xqlite, :savepoint, :release].

@spec remove_authorizer(conn()) :: :ok | error()

Removes any authorizer installed on the connection.

Safe to call when none is installed (no-op). After removal, statement preparation is unrestricted again.

No telemetry is emitted.

@spec remove_busy_policy(conn()) :: :ok | error()

Removes the busy retry policy from the connection.

Observers registered with register_busy_observer/2 keep receiving {:xqlite_busy, …} messages; without a policy SQLite surfaces SQLITE_BUSY immediately after they fire. Safe to call when no policy is installed.

@spec reset(stmt()) :: :ok | error()

Resets a prepared statement so it can be stepped from the start again.

Bindings are preserved (SQLite semantics); use clear_bindings/1 to drop them to NULL. Always returns :ok for a live statement — sqlite3_reset's return code echoes the most recent step error, not the reset itself.

@spec restore(conn(), String.t(), String.t()) :: :ok | error()

Restores a schema from a file.

Replaces the named schema (default "main") with the contents of the file at src_path. Existing data in that schema is overwritten.

@spec rollback(conn()) :: :ok | error()

Rolls back the current transaction. Emits [:xqlite, :transaction, :rollback] with reason: :user_initiated.

SQLite-internal rollbacks (constraint violations, deferred-FK failures at commit time) surface as errors from commit/1 rather than passing through here — those events come from the register_rollback_hook/2 fan-out instead.

@spec rollback_to_savepoint(conn(), String.t()) :: :ok | error()

Rolls back to a savepoint without releasing it. Emits [:xqlite, :savepoint, :rollback_to].

Note: this does NOT invoke SQLite's rollback_hook — that fires only for outer-transaction rollbacks. Use register_rollback_hook/2 for outer rollback observability; this telemetry event is what's available for partial-rollback observability.

@spec savepoint(conn(), String.t()) :: :ok | error()

Creates a savepoint with the given name. Emits [:xqlite, :savepoint, :create].

@spec schema_columns(conn(), String.t()) ::
  {:ok, [Xqlite.Schema.ColumnInfo.t()]} | error()

Returns column details for a table or view as Xqlite.Schema.ColumnInfo structs (PRAGMA table_xinfo), or {:ok, []} when the table does not exist.

Wraps XqliteNIF.schema_columns/2. No telemetry is emitted.

@spec schema_databases(conn()) :: {:ok, [Xqlite.Schema.DatabaseInfo.t()]} | error()

Lists all databases attached to the connection as Xqlite.Schema.DatabaseInfo structs (PRAGMA database_list).

Wraps XqliteNIF.schema_databases/1. No telemetry is emitted.

@spec schema_foreign_keys(conn(), String.t()) ::
  {:ok, [Xqlite.Schema.ForeignKeyInfo.t()]} | error()

Returns the foreign keys defined on a table as Xqlite.Schema.ForeignKeyInfo structs (PRAGMA foreign_key_list).

Wraps XqliteNIF.schema_foreign_keys/2. No telemetry is emitted.

@spec schema_index_columns(conn(), String.t()) ::
  {:ok, [Xqlite.Schema.IndexColumnInfo.t()]} | error()

Returns the columns of an index as Xqlite.Schema.IndexColumnInfo structs (PRAGMA index_xinfo), ordered by position in the index.

Wraps XqliteNIF.schema_index_columns/2. No telemetry is emitted.

@spec schema_indexes(conn(), String.t()) ::
  {:ok, [Xqlite.Schema.IndexInfo.t()]} | error()

Returns all indexes on a table as Xqlite.Schema.IndexInfo structs (PRAGMA index_list), including those backing PRIMARY KEY and UNIQUE constraints.

Wraps XqliteNIF.schema_indexes/2. No telemetry is emitted.

@spec schema_list_objects(conn(), String.t() | nil) ::
  {:ok, [Xqlite.Schema.SchemaObjectInfo.t()]} | error()

Lists tables, views, and virtual tables as Xqlite.Schema.SchemaObjectInfo structs (PRAGMA table_list).

schema defaults to nil; pass "main", "temp", or an attached database name for predictable results. Wraps XqliteNIF.schema_list_objects/2. No telemetry is emitted.

@spec serialize(conn(), String.t()) :: {:ok, binary()} | error()

Serializes a database to a contiguous binary.

Returns a binary snapshot of the entire database — an atomic, point-in-time copy. No pages are locked during serialization.

schema identifies which attached database to serialize. Defaults to "main". Use "temp" for the temp database or the name of an attached database.

@spec set_authorizer(conn(), [atom()]) :: :ok | error()

Installs a deny-list authorizer on the connection.

SQLite consults an authorizer callback while preparing every statement. This installs one that denies a fixed set of action kinds: if a statement attempts any denied action, preparation fails and the call returns {:error, {:authorization_denied, extended_code, message}} (the extended code is SQLite's SQLITE_AUTH family). Everything else is allowed.

denied_actions is a list of action-kind atoms. The set mirrors SQLite's authorizer action codes — :select, :read, :insert, :update, :delete, :transaction, :savepoint, :pragma, :attach, :detach, :alter_table, :reindex, :analyze, :function, :recursive, the create_* / drop_* object verbs (:create_table, :drop_index, :create_trigger, :create_view, :create_vtable, :drop_vtable, …) including their *_temp_* variants, and :unknown for action codes a future SQLite reports that this build does not map. An unrecognized atom returns {:error, {:invalid_authorizer_action, atom}} and installs nothing — the list is validated in full before anything changes.

Single slot per connection: a second call replaces the previous list, and remove_authorizer/1 clears it. Both are idempotent.

Limits (v1)

• Action-kind granularity only. The decision is made purely on the action kind; the table, column, trigger and database arguments SQLite passes to the authorizer are ignored. You cannot (yet) deny DELETE on one table while allowing it on another.
• Deny-only. An action is allowed or denied (SQLite's DENY). The IGNORE disposition (silently treat the access as a NULL/no-op) is not exposed.

Caveat — denying :pragma disables get_pragma/set_pragma

XqliteNIF.get_pragma/2 and set_pragma/3 run PRAGMA statements, which SQLite authorizes as the :pragma action; the schema-introspection helpers lean on PRAGMAs too. Denying :pragma therefore makes all of them fail with {:error, {:authorization_denied, _, _}}. Deny it only when you intend to lock those paths out as well.

No telemetry is emitted for authorizer install/remove or for denials.

Examples

iex> {:ok, conn} = Xqlite.open_in_memory()
iex> XqliteNIF.execute(conn, "CREATE TABLE t(id INTEGER)", [])
{:ok, 0}
iex> Xqlite.set_authorizer(conn, [:delete])
:ok
iex> match?({:error, {:authorization_denied, _, _}}, XqliteNIF.execute(conn, "DELETE FROM t", []))
true
iex> match?({:ok, _}, XqliteNIF.query(conn, "SELECT id FROM t", []))
true
iex> Xqlite.set_authorizer(conn, [:bogus])
{:error, {:invalid_authorizer_action, :bogus}}
iex> Xqlite.remove_authorizer(conn)
:ok
iex> XqliteNIF.execute(conn, "DELETE FROM t", [])
{:ok, 0}

@spec set_busy_policy(
  conn(),
  keyword()
) :: :ok | error()

Sets the busy retry POLICY on the connection.

When SQLite encounters a locked database (another writer holds RESERVED+) the policy decides whether to retry or surface SQLITE_BUSY to the caller. The policy is single-slot by design — a retry decision cannot compose. To OBSERVE contention (telemetry, structured logging, adaptive backoff), register any number of subscribers with register_busy_observer/2; the two halves are independent.

Options

• :max_retries (non-negative integer, default 50) — stop after this many retries and let the caller see SQLITE_BUSY.
• :max_elapsed_ms (non-negative integer, default 5_000) — absolute time ceiling in milliseconds from the busy slot's first installation.
• :sleep_ms (non-negative integer, default 10) — milliseconds to sleep between retries. Zero disables the pause (tight spin; rarely what you want).

Replacing an existing policy is atomic; observers are unaffected.

@spec set_pragma(conn(), String.t() | atom(), term()) :: {:ok, term()} | error()

Sets a PRAGMA value on the connection.

Wraps XqliteNIF.set_pragma/3 and emits [:xqlite, :pragma, :set].

@spec sqlite_version() :: {:ok, String.t()} | error()

Returns the version string of the linked SQLite C library.

Needs no connection. Wraps XqliteNIF.sqlite_version/0. No telemetry is emitted.

@spec step(stmt()) :: {:row, [sqlite_value()]} | :done | error()

Advances a prepared statement one row.

Returns {:row, values}, :done when exhausted, or {:error, reason}. Stepping past :done without a reset/1 returns whatever SQLite reports for the re-step (a fresh automatic rerun on modern SQLite).

@spec stream(conn(), String.t(), list() | keyword(), keyword()) ::
  Enumerable.t() | error()

Creates a stream that executes a query and emits rows as string-keyed maps.

This provides a high-level, idiomatic Elixir Stream for processing large result sets without loading them all into memory at once. Rows are fetched from the database in batches as the stream is consumed.

Options

• :batch_size (integer, default: 500) - The maximum number of rows to fetch from the database in a single batch.
• :type_extensions (list of modules, default: []) - A list of modules implementing the Xqlite.TypeExtension behaviour. Parameters are encoded before binding, and result values are decoded as rows are fetched. Extensions are applied in list order; the first match wins.

• :on_error (:raise | :halt | :emit_error, default: :raise) - How a mid-fetch error (e.g. an invalid-UTF-8 TEXT value) is surfaced. The stream's element shape FOLLOWS the mode:

  • :raise (default) - happy path yields raw row maps; a mid-fetch error raises Xqlite.StreamError, whose :reason field holds the structured error term. A failed read can never masquerade as a completed stream.
  • :halt - happy path yields raw row maps; a mid-fetch error is logged and the stream stops. LOSSY: the result set is silently truncated and the consumer receives no error signal.
  • :emit_error - yields a uniformly tagged stream: {:ok, row} for each row, followed by a terminal {:error, reason} on failure. An unsupported value returns {:error, {:invalid_on_error, value}} at stream open.

Examples

iex> {:ok, conn} = Xqlite.open_in_memory()
iex> XqliteNIF.execute_batch(conn, "CREATE TABLE users(id, name); INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');")
:ok
iex> Xqlite.stream(conn, "SELECT id, name FROM users;") |> Enum.to_list()
[%{"id" => 1, "name" => "Alice"}, %{"id" => 2, "name" => "Bob"}]

Returns an Enumerable.t() on success or {:error, reason} on setup failure. Callers must pattern-match the result before piping — this is intentional, as returning a stream that silently errors on first consume would hide setup failures (e.g., invalid SQL, closed connection).

Errors that occur during stream consumption (e.g. an invalid-UTF-8 value, or the connection being lost mid-stream) are surfaced according to the :on_error option above — by default they raise Xqlite.StreamError.

@spec total_changes(conn()) :: {:ok, non_neg_integer()} | error()

Returns the total number of rows changed by all INSERT, UPDATE, and DELETE statements since the connection was opened, including changes made by triggers. Wraps XqliteNIF.total_changes/1. No telemetry is emitted.

@spec transaction_status(conn()) :: {:ok, boolean()} | error()

Returns whether the connection is currently inside a transaction.

{:ok, true} after begin/2 and before commit/1 or rollback/1, {:ok, false} in autocommit mode. Wraps XqliteNIF.transaction_status/1. No telemetry is emitted.

@spec txn_state(conn(), String.t() | nil) ::
  {:ok, :none | :read | :write | :unknown} | error()

Returns the transaction state of a schema: :none, :read, :write, or :unknown (a future SQLite state not mapped yet).

schema defaults to nil, meaning "main". Wraps XqliteNIF.txn_state/2 (see it for why there is no full five-state lock ladder). No telemetry is emitted.

@spec unregister_busy_observer(conn(), non_neg_integer()) :: :ok | error()

Unregisters a busy-contention observer by handle.

Idempotent — an unknown or already-removed handle is a no-op.

@spec unregister_progress_hook(conn(), non_neg_integer()) :: :ok | error()

Unregisters a progress-tick subscriber by handle.

Idempotent — unregistering an unknown handle returns :ok. Returns {:error, :connection_closed} if the connection is closed.

@spec wal_checkpoint(conn(), atom(), String.t()) :: {:ok, map()} | error()

Performs a WAL checkpoint on the connection.

mode is one of :passive (default), :full, :restart, or :truncate. schema is the attached-database name (default "main").

Returns {:ok, %{log_pages, checkpointed_pages, busy?}} on success.