@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.

@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 busy_timeout(conn(), non_neg_integer()) :: :ok | error()

Sets a plain sqlite3_busy_timeout on the connection, replacing any xqlite-installed busy handler cleanly.

Calls remove_busy_handler/1 first (so our internal state is reclaimed and {:xqlite_busy, …} messages stop for an understood reason), then sets PRAGMA busy_timeout = ms.

Prefer this helper over reaching for PRAGMA busy_timeout directly: the raw PRAGMA silently replaces any installed xqlite handler at the SQLite level, stopping {:xqlite_busy, …} deliveries 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 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 commit(conn()) :: :ok | error()

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

@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 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()) ::
  {: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.

@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 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 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 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 query(conn(), String.t(), list() | 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.

@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_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_busy_handler(conn()) :: :ok | error()

Removes any busy handler installed on the connection.

Safe to call when no handler is installed (no-op on both the SQLite and xqlite sides). After removal, SQLite returns SQLITE_BUSY immediately on contention unless a busy_timeout is subsequently set (see busy_timeout/2).

@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 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_busy_handler(conn(), pid(), keyword()) :: :ok | error()

Installs a busy handler on the connection.

When SQLite encounters a locked database (another writer holds RESERVED+) the handler decides whether to retry or surface SQLITE_BUSY to the caller. Each invocation is also forwarded to pid as

{:xqlite_busy, retries_so_far, elapsed_ms}

so callers can observe contention (telemetry, structured logging, adaptive backoff).

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 first busy event in the window.
• :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 handler is atomic: the previous handler's state is reclaimed before the new one takes effect.

@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 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.

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., database connection lost mid-stream) will be logged and will cause the stream to halt.

@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.