Pretty-print a summary: path, active schema, savepoint depth, total changes.

Re-export value type for convenience.

#239: per-query cost/stats signal for an external cost-based cache, re-exported from Granary_sql.Exec.query_stats. rows_examined is the rows pulled from a base table/index scan (the work signal — a full scan behind a selective filter reads rows_examined = N returning one row); rows_returned is the result size once the stream is drained; used_index is the plan-time fact that the base access is an index/rowid/FTS seek rather than a full scan. See query_with_stats / iter_with_stats.

Open a fresh in-memory database. clock is an optional Unix-timestamp provider used by SQL date/time functions when invoked with the literal 'now'. Omit for MirageOS-friendly cores that have no Unix dependency.

Open a SQL engine on any block device given as I/O callbacks. Use with Granary_mirage_block.Mirage_backend.Make(B) to build the callbacks from a Mirage_block.S device. Pass ~n_pages:0L for Mirage adapters; the adapter handles device-capacity bounds internally. ~close is called by Db.close.

clock and durability are open-options forwarded to of_store: durability sets the database-wide durability knob (full/batched/off) before the catalog is loaded.

This is the platform-agnostic entry point. Unix file convenience constructors (open_file / open_file_wal) live in the granary.unix driver library so this core carries no unix dependency (#170).

Wrap an already-open Granary_store.Store.t as a database handle, loading its catalog, views, and triggers. file_path records the on-disk path for file-backed handles so VACUUM can rebuild in place; omit it for in-memory / arbitrary block devices. durability sets the database-wide durability knob (full/batched/off) on the store before the catalog is loaded — use this to configure the store's fsync policy at open time without needing a raw store handle afterwards. Used by the granary.unix driver and by ATTACH.

File operations the engine needs for ATTACH and VACUUM. The core has no OS/filesystem dependency (#170); a platform driver (e.g. granary.unix) supplies these via set_file_provider. Without a provider, ATTACH and VACUUM fail with a clear error.

Install the process-wide file provider used by ATTACH and VACUUM.

Close the database, flushing and releasing the underlying store.

Create a lightweight worker handle sharing the same underlying store. Equivalent to let* () = Lwt.return_unit in of_store (store t). Used by Jepsen-style concurrent workloads where each worker needs its own explicit_txn without exposing the raw store.

Number of WAL fsyncs performed since open. Returns 0 for non-WAL databases. Exposed for #77 group-commit testing.

Re-export of the internal-events type (#382).

Register/clear the internals-monitor observer on this database's store. No-op for in-memory databases. The callback should be cheap and non-blocking (see Granary_store.Store.set_event_callback).

tree_of_table t name is the storage tree id backing table name in the active schema, or None if no such table exists or the table has no real on-disk tree (e.g. an ephemeral/CTE table, or a legacy zero-tid columnar table, which carry a negative sentinel tree id). Used by the internals monitor to filter page events by table (#385).

catalog t is the active in-memory catalog backing t, for read-only schema/type projection — column names, types, and NOT NULL constraints via Granary_catalog.Catalog.list_tables / Granary_catalog.Catalog.find_table. The result reflects the schema at call time; the engine may swap its catalog on recovery, so treat the returned handle as a snapshot rather than caching it across a reopen. This is the live handle: Catalog.t also exposes mutators (drop_table, add_column, …), so "do not mutate it — schema changes go through SQL DDL" is a caller contract, not enforced. See #433 for a possible opaque read-only projection should this grow more consumers.

Rebuild the database file in place: copies every tree from the current file into a fresh sibling path ^ ".vacuum-tmp", then atomically renames it over the original. This drops free-list pages and re-packs everything densely.

Only works on file-backed databases (opened via the granary.unix driver); in-memory and arbitrary-block-device handles raise Failure, as does any handle when no file provider is installed (see set_file_provider).

Must not be called inside an explicit transaction. Any open prepared statements created from the previous file will continue to work logically but observe the recompacted file. Phase 37 / #120.

Execute a DDL or DML statement (CREATE TABLE, INSERT, UPDATE, ...). Returns Ok () on success, Error e on failure.

Like execute, but returns the rows-affected count. For DDL the count is 0; for INSERT it is 1; for UPDATE it is the number of rows whose contents were modified.

Execute a query (SELECT). Returns Ok stream on success, Error e on failure. The stream is lazy — rows are produced on demand.

#239: like query, but also returns a per-query cost/stats record (rows_examined, rows_returned, used_index) for an external cost-based cache. The record's counters are populated as the returned stream is consumed — read them once it is fully drained. See Granary_sql.Exec.query_stats.

query_as_of t target sql (#266) runs a read-only sql query against the database as it existed at target (a past txn id or timestamp). Requires the db to have been opened with ~as_of_history:true; otherwise the result carries History_unavailable. As-of reads require an active retention floor set via history_pin: with no floor every target resolves to History_pruned, and the floor is not retroactive — pin before the writes you want to retain across. History_pruned also when target predates the retained floor. Schema is read at HEAD: a query whose table had DDL after target may misinterpret older rows (schema-as-of is out of scope, #266). As-of resolves against whichever database the statement routes to — MAIN, or the active ATTACHed schema (#412). A single query cannot span MAIN and an attached db at one target: their commit orders are independent, so routing consults exactly one store's history.

history_pin ?schema t ~txn_id (#266/#412) sets the retention floor at txn_id for schema (default "main"; otherwise a currently ATTACHed schema): the committed root at or before txn_id is retained so query_as_of can reach it. No-op when as-of history is not enabled.

• raises Invalid_argument

  if schema is neither "main" nor attached.

history_floor ?schema t (#266/#412) is schema's current retention floor txn id, or None when no floor is pinned (or as-of history is not enabled).

• raises Invalid_argument

  if schema is neither "main" nor attached.

history_release ?schema t (#266/#412) clears schema's retention floor, allowing pruning of previously pinned historical roots.

• raises Invalid_argument

  if schema is neither "main" nor attached.

history_log ?schema t (#266/#412) is schema's recorded commit history (the <path>.aslog sidecar), oldest first. Empty when as-of history is not enabled.

• raises Invalid_argument

  if schema is neither "main" nor attached.

#240: the set of user tables whose rows a write statement actually mutated, including tables touched indirectly by triggers and FK cascades. Sorted and deduplicated; internal/system tables are excluded. Enables an external read cache to invalidate the tables whose row data changed.

Scope: row-level DML only. This signal reports Db.execute-style row mutations (INSERT / UPDATE / DELETE, upserts, cascades, trigger bodies, columnar and FTS writes). It does not report schema-changing or destructive DDL — DROP TABLE, and ALTER TABLE in all its forms (ADD/DROP/RENAME COLUMN, RENAME TABLE) — even when the DDL physically rewrites every row (e.g. ALTER TABLE … DROP COLUMN, which reshapes the stored rows). Such a statement yields an empty list here. A consumer that caches query results MUST invalidate on schema changes through a separate schema-version / fingerprint signal (cf. #174); an empty result from a DDL statement therefore does not imply the table's observable contents are unchanged.

#417 Phase 0: one row-level mutation in the delta feed. rowid is the row's int64 rowid; row/old_row/new_row are the full rows involved. Re-exported from Granary_sql.Exec.row_change.

#417: the per-table row-level deltas a write statement produced — (table, changes) pairs sorted by table name, each table's changes in application order. Same name/scope rules as dirty_tables: user tables only, internal sqlite_… objects excluded, DDL out of band.

Like execute, but also returns the dirty_tables the statement mutated. The list is empty for a no-op write (e.g. INSERT OR IGNORE that inserts nothing) and for all DDL (including row-rewriting DDL such as ALTER TABLE … DROP COLUMN and DROP TABLE) — see the dirty_tables scope note; DDL invalidation is out of band.

Like execute_change_count, but also returns the dirty_tables the statement mutated alongside the rows-affected count.

#417: like execute_with_dirty, but returns the row-level table_changes delta feed (rowid + old/new rows) instead of just the table names — the input an incremental view-maintenance layer consumes. Empty for no-op writes and DDL, same as execute_with_dirty.

Phase 0 coverage. The feed covers ordinary rowid-table DML: INSERT, UPDATE, DELETE, REPLACE (delete-old + insert-new), UPSERT DO UPDATE, and rows mutated indirectly by FK cascades and triggers. It does not yet carry row-level deltas for FTS5 or columnar tables — those still report only their name via execute_with_dirty and are absent here. A consumer that must invalidate on FTS/columnar writes uses execute_with_dirty alongside this; full FTS/columnar row capture is a follow-up (#418).

Rowid identity. Deltas are keyed by rowid. An UPDATE that changes a row's INTEGER-PK alias moves it to a new rowid — a change of identity — so it surfaces as a Deleted of the old rowid paired with an Inserted at the new one, not an Updated. Conversely, a REPLACE that overwrites the same alias rowid is a physical in-place write and surfaces as a single Inserted of that rowid (no paired Deleted); a consumer treats "inserted a rowid it already holds" as a replace.

Multiple deltas per rowid. Within one statement a rowid may appear in more than one change — e.g. a self-referential FK ON UPDATE CASCADE whose cascade updates a row that the statement also matches directly. Consumers must fold deltas in order rather than assume one per rowid (#418).

#427: register cb to fire after every commit that changes reactive view view_name's materialisation. cb receives the native row_change diffs applied to _rv_<view_name> (Deleted/Inserted pairs; a changed aggregate row is a delete of the old plus an insert of the new). Commits that leave the view unchanged — and DDL — fire nothing. A no-op if view_name is not a reactive view.

#387: the projected output column names for a row-returning sql, without executing it. Parses and binds sql against the current schema and returns a best-effort name per result column: a SELECT alias or bare column name where known, * expanded to the source table's columns, and a positional col_N placeholder for anonymous expressions. Intended for header display (e.g. the REPL); the list length matches the row width query produces for the same statement.

#264: stream a logical SQL dump (a .dump-style export) of the database to sink, one chunk at a time.

The output is a self-contained SQL script that recreates the database when replayed statement-by-statement through execute: PRAGMA foreign_keys=OFF;, then for each table its CREATE TABLE followed by INSERT statements for its rows, then each FTS5 virtual table's CREATE VIRTUAL TABLE followed by INSERTs for its content, then explicit indexes, views (in dependency order) and triggers. Tables are emitted in creation order. Generated-column values are omitted (recomputed on insert); implicit PRIMARY KEY indexes the CREATE TABLE already implies are not re-emitted.

The whole script is wrapped in BEGIN/COMMIT (after the leading PRAGMA foreign_keys=OFF;, which stays outside the transaction), so a restore applies atomically — matching sqlite3 .dump (#281). This became possible once #269 removed the DDL-in-transaction deadlock; every statement the dump emits is transactional, so there is no per-statement-autocommit fallback. A consequence: replay the script as-is — do not wrap it in your own BEGIN/COMMIT, as the engine rejects a nested transaction.

Point-in-time row data (#274). Every table's row data is read through one read-only snapshot of the committed state, taken when the dump begins (when an explicit transaction is active, its view is used instead), so the emitted rows reflect a single consistent moment even if other writers commit concurrently while the dump runs — matching sqlite3 .dump, which previously differed by reading each table in its own snapshot (a torn dump). View and trigger DDL is read through that same view too (#322/#323/#329): the shared snapshot in autocommit, or the explicit transaction when one is active — so the schema section is always consistent with the row data (point-in-time against a concurrent CREATE/DROP VIEW|TRIGGER commit, and read-your-own -writes inside a transaction). Table/index DDL and the AUTOINCREMENT high-water still come from the in-memory catalog (a separate consistency surface), so for a fully consistent result those should be quiescent during the dump.

FTS5 content is dumped (#319/#330). An FTS5 table's CREATE VIRTUAL TABLE is emitted followed by INSERT INTO t(rowid, ..) statements for its stored content, so a replay re-inserts the original rows (rebuilding the index) with their original rowids — a delete leaves a rowid gap that the restore preserves rather than re-packing, matching how sqlite3 .dump round-trips an FTS table.

Composite / table-level PRIMARY KEYs round-trip as plain UNIQUE indexes (this engine's internal representation): the data is preserved, but the restored schema reports no PRIMARY KEY and permits NULLs in those columns.

schema_only omits all INSERTs; data_only omits all DDL (leaving only the row INSERTs). Both modes carry the same BEGIN/COMMIT wrapper as a full dump. Passing both yields an essentially empty dump.

#264: like dump, but collects the whole dump into a single string. Convenient for small databases; for large ones prefer dump with a streaming sink to avoid materializing the entire script in memory.

Format an error value for human-readable output.

A compiled prepared statement. Can be reused with different parameter bindings via run and iter.

Compile sql into a prepared statement. Returns Error if the SQL cannot be parsed or the schema check fails.

Execute a write statement (INSERT, UPDATE, DELETE) with the given positional parameter values. Returns the rows-affected count.

Like run, but also returns the dirty_tables the prepared write mutated alongside the rows-affected count.

Execute a read statement (SELECT) with the given positional parameter values. Returns a stream of result rows.

Inside an explicit transaction the stream observes the transaction's own uncommitted writes (read-your-own-writes, #262). The stream is a stable snapshot taken when iteration begins: rows written to the same table later in the transaction are not retroactively seen by an in-flight stream, and the stream remains safe to drain after a subsequent write or COMMIT.

#239: like iter, but also returns a per-query cost/stats record populated as the returned stream is consumed. See Granary_sql.Exec.query_stats.

Release resources held by a prepared statement. No-op in this implementation, but should be called for forward compatibility.

Look up the 0-based slot index for a named parameter. Returns None if the name was not found in the prepared statement.

Build a parameter array from a named association list. Unnamed or unknown parameters are left as V_null.