Struct Connection 

pub struct Connection { /* private fields */ }

Implementations

impl Connection

pub async fn open(path: impl Into<String>) -> Result<Self>

Open a connection.

Creates an empty in-memory database. Expression-only SELECT and table-backed DML (CREATE TABLE, INSERT, SELECT FROM, UPDATE, DELETE) are supported.

pub async fn open_existing(path: impl Into<String>) -> Result<Self>

Open an existing file-backed database for reading and writing.

Unlike Self::open, this never creates or initializes the main database file. Missing and zero-length paths return FrankenError::CannotOpen, while malformed database images return FrankenError::DatabaseCorrupt without changing their contents.

pub async fn open_existing_with_expected_identity( path: impl Into<String>, expected_identity: FileIdentity, ) -> Result<Self>

Open an existing file-backed database only if its already-open VFS handle has expected_identity.

The identity comparison happens before any database read, rollback journal probe, or recovery action, so the main database handle is bound to the object leased by the caller. The expected identity binds only the main database handle: journal, WAL, WAL-FEC, and shared-memory artifacts are still resolved from path. Callers must therefore pass the exact cooperative database pathname, not a symlink or hard-link alias, and retain the descriptor used to derive expected_identity until this method returns. They must also prevent namespace replacement for the duration of open and recovery (for example with a cooperative writer lease in a trusted parent directory).

pub async fn open_reserved_with_expected_identity( path: impl Into<String>, expected_identity: FileIdentity, ) -> Result<Self>

Initialize a caller-reserved empty database file only if its VFS handle has expected_identity.

The path must already exist and be empty when opened. This is the create-new counterpart to Self::open_existing_with_expected_identity: it binds initialization to the descriptor that reserved the pathname rather than dropping that descriptor and trusting a later path lookup. The caller must retain that descriptor until this method returns and pass the exact cooperative database pathname, not a symlink or hard-link alias, because auxiliary artifacts are derived from this pathname. The containing namespace must remain protected from replacement throughout initialization.

pub async fn open_strict_multi_process(path: impl Into<String>) -> Result<Self>

Open a connection with strict multi-process refusal enabled.

Convenience shortcut for callers (CI harnesses, multi-agent workloads) that want loud failures on ambiguous concurrency states rather than silent corruption. Equivalent to:

let mut env = ConnectionEnv::default();
env.set_strict_multi_process(true);
Connection::open_with_env(path, env)

See frankensqlite#81 and ConnectionEnv::set_strict_multi_process.

pub async fn open_with_page_size( path: impl Into<String>, page_size_bytes: u32, ) -> Result<Self>

Open a connection while requesting a specific page size for newly created databases.

Existing database files ignore the requested page size and continue to use the size encoded in their on-disk header.

pub async fn import_bytes(bytes: &[u8]) -> Result<Self>

Import a self-contained SQLite database image into a new in-memory connection.

pub async fn open_schema_only(path: impl Into<String>) -> Result<Self>

Open a connection that loads only the database schema (table definitions, indexes, triggers, views) without reading any row data into the in-memory MemDatabase.

This is dramatically faster for large databases when the caller only needs schema metadata or will execute queries through pager-backed cursors (the default for file-backed databases).

Row data is still accessible through the pager’s B-tree cursor stack; only the MemDatabase compatibility image is left empty.

Examples

let conn = Connection::open_schema_only("large.db")?;
// Schema is available, queries work through pager-backed cursors.
let rows = conn.query("SELECT count(*) FROM big_table")?;

pub async fn open_existing_schema_only(path: impl Into<String>) -> Result<Self>

Open an existing file-backed database for reading and writing while loading only its schema into the compatibility MemDatabase.

This combines the bounded-memory behavior of Self::open_schema_only with the existing-only, writable contract of Self::open_existing. The main database file is never created or initialized by this method.

pub async fn open_existing_schema_only_deferred_fts5( path: impl Into<String>, ) -> Result<Self>

#368 defect 3: like open_existing_schema_only but DEFERS FTS5 shadow validation/hydration at open. The schema reload keeps bare, empty FTS5 vtab instances and never reads/validates %_data, so a database whose FTS5 shadow structure is corrupt (which otherwise fails every open) can still be opened to drop+recreate the corrupt shadow. Use ONLY for FTS repair: FTS5 queries against such a connection see an empty index until the shadow is rebuilt.

pub async fn open_existing_schema_only_deferred_fts5_with_env( path: impl Into<String>, env: ConnectionEnv, ) -> Result<Self>

open_existing_schema_only_deferred_fts5 with an explicit runtime environment.

pub async fn open_schema_only_with_expected_identity( path: impl Into<String>, expected_identity: FileIdentity, ) -> Result<Self>

Open a schema-only connection only if the read-only VFS handle has expected_identity.

Identity verification occurs before the database header, live WAL, or platform advisory sidecars are inspected. The caller must pass the exact cooperative database pathname, not a symlink or hard-link alias, and retain the descriptor used to derive expected_identity until this method returns, because auxiliary artifacts are derived from path and filesystem identities may be recycled after the last handle closes. The containing namespace must remain protected from replacement throughout the open.

pub async fn open_existing_schema_only_with_expected_identity( path: impl Into<String>, expected_identity: FileIdentity, ) -> Result<Self>

Open a writable, existing-only schema connection if the main database handle has expected_identity.

The cooperative-path and no-alias requirements documented on Self::open_existing_with_expected_identity apply unchanged.

pub async fn open_schema_only_with_env( path: impl Into<String>, env: ConnectionEnv, ) -> Result<Self>

Open a schema-only connection with an explicit runtime environment.

Behaves like open_schema_only but allows specifying a custom ConnectionEnv.

pub async fn open_existing_schema_only_with_env( path: impl Into<String>, env: ConnectionEnv, ) -> Result<Self>

Open a writable, existing-only schema connection with an explicit runtime environment.

pub async fn open_schema_only_with_expected_identity_and_env( path: impl Into<String>, expected_identity: FileIdentity, env: ConnectionEnv, ) -> Result<Self>

Open an identity-bound schema-only connection with an explicit runtime environment.

The exact cooperative-path and no-alias requirements documented on Self::open_schema_only_with_expected_identity also apply here.

pub async fn open_existing_schema_only_with_expected_identity_and_env( path: impl Into<String>, expected_identity: FileIdentity, env: ConnectionEnv, ) -> Result<Self>

Open an identity-bound, writable, existing-only schema connection with an explicit runtime environment.

pub async fn open_with_env( path: impl Into<String>, env: ConnectionEnv, ) -> Result<Self>

Open a connection with an explicit runtime environment.

The supplied ConnectionEnv selects the process-global or custom runtime context whose per-database region this connection joins.

pub async fn open_existing_with_env( path: impl Into<String>, env: ConnectionEnv, ) -> Result<Self>

Open an existing file-backed database with an explicit runtime environment, without creating or initializing the main database file.

pub async fn open_existing_with_expected_identity_and_env( path: impl Into<String>, expected_identity: FileIdentity, env: ConnectionEnv, ) -> Result<Self>

Open an existing file-backed database with an explicit runtime environment only if its already-open VFS handle has expected_identity.

The exact cooperative-path and no-alias requirements documented on Self::open_existing_with_expected_identity also apply here.

pub async fn open_reserved_with_expected_identity_and_env( path: impl Into<String>, expected_identity: FileIdentity, env: ConnectionEnv, ) -> Result<Self>

Initialize an identity-bound caller-reserved empty file with an explicit runtime environment.

The exact cooperative-path and no-alias requirements documented on Self::open_reserved_with_expected_identity also apply here.

pub async fn open_with_page_size_and_env( path: impl Into<String>, page_size_bytes: u32, env: ConnectionEnv, ) -> Result<Self>

Open a connection with an explicit runtime environment and requested page size for newly created databases.

Existing database files keep the page size already encoded in their header; the request only affects brand-new databases.

pub async fn import_bytes_with_env( bytes: &[u8], env: ConnectionEnv, ) -> Result<Self>

Import a self-contained SQLite database image into an in-memory connection using the supplied runtime environment.

pub fn path(&self) -> &str

Returns the configured database path.

pub async fn file_identity(&self) -> Result<Option<FileIdentity>>

Return the identity of the main database object held by this connection.

This is derived from the VFS’s already-open main-file handle, never by looking up Self::path. File-backed Unix connections return Some; memory and backends without a stable descriptor identity return None.

pub async fn export_bytes(&self) -> Result<Vec<u8>>

Export the current database as a self-contained SQLite database image.

pub fn memory_stats(&self) -> Result<ConnectionMemoryStats>

Snapshot current connection memory usage and page-cache state.

pub fn background_status(&self) -> Result<()>

Return the background-runtime health for this connection’s database.

pub fn stmt_microbatch_counters(&self) -> (u64, u64)

Test/observability: return (hits, renewals) since connection open.

pub fn last_insert_rowid(&self) -> i64

Return the most recent successful INSERT rowid on this connection.

pub fn set_reject_mem_fallback(&self, reject: bool)

Enable parity-certification mode (bd-2ttd8.1).

When enabled, all VDBE cursor operations must route through the real Pager+BtreeCursor stack. The MemPageStore fallback is rejected, causing OpenRead/OpenWrite to fail if no pager transaction is available. Use this in tests to verify that the full storage stack is wired correctly.

pub fn set_strict_mem_fallback_rejection(&self, strict: bool)

Enable strict non-VDBE fallback rejection for certifying runs.

When enabled together with reject_mem_fallback, dispatching to interpreted in-memory fallback paths (for example JOIN/GROUP BY materialization fallbacks) returns an error instead of silently continuing.

pub fn fallback_decision_snapshot(&self) -> FallbackDecisionSnapshot

Return the bounded fallback-decision evidence observed since open or the most recent reset.

pub fn reset_fallback_decision_evidence(&self)

Clear all connection-local fallback-decision evidence.

pub fn pager_backend_kind(&self) -> &'static str

Returns the kind of pager backend in use (e.g. “memory”, “iouring”, or “unix”).

pub fn validate_parity_cert_backend(&self) -> Result<(), String>

Validate that the pager backend is suitable for parity-certification.

When reject_mem_fallback is enabled, the pager SHOULD be file-backed (not :memory:) for meaningful parity testing. This method returns Err if parity-cert mode is active but the pager is memory-only.

Note: This is a diagnostic check, not an enforcement gate. In-memory pagers can still be used in parity-cert mode (they have a real SimplePager behind them), but file-backed pagers provide stronger guarantees about I/O path coverage.

pub fn last_local_commit_seq(&self) -> Option<u64>

Returns the most recent commit sequence assigned to a successful COMMIT on this connection.

Returns None when this connection has not committed yet.

pub fn current_concurrent_snapshot_seq(&self) -> Option<u64>

Returns the active concurrent transaction snapshot sequence observed at BEGIN CONCURRENT time for this connection.

Returns None when no concurrent transaction is active.

pub fn root_cx(&self) -> &Cx

Returns a reference to the root capability context for this connection.

pub fn bind_operation_cx(&self, cx: &Cx) -> OperationCxGuard<'_>

Bind a worker-owned context to subsequent operation-context derivations.

This is the cancellation bridge for actor facades. The supplied context must be derived from this connection’s root so it retains the worker’s capabilities and native I/O attachment. Dropping the returned guard restores the previous binding, including during unwinding.

pub fn with_operation_cx<T>(&self, cx: &Cx, operation: impl FnOnce() -> T) -> T

Run one actor-dispatched operation under a worker-root-derived context.

pub fn trace_v2(&self, mask: TraceMask, callback: Option<TraceCallback>)

Register or clear sqlite3_trace_v2-compatible callbacks.

Passing Some(callback) enables callback delivery for the requested mask. Passing None clears any existing registration.

pub async fn close(self) -> Result<()>

Close the connection and perform pager/WAL shutdown steps.

On close:

1. Roll back any active transaction.
2. Run a passive checkpoint (WAL -> DB).
3. Mark the connection as closed so Drop doesn’t repeat cleanup.

pub async fn close_without_checkpoint(self) -> Result<()>

Close the connection without forcing a final WAL checkpoint.

This preserves already-committed state in the WAL and is appropriate when the process is about to exit or when a caller explicitly wants to avoid paying close-time checkpoint latency. Subsequent opens will recover and publish the WAL contents normally.

pub async fn close_in_place(&mut self) -> Result<()>

Close the connection in place while retaining the Connection value on error so callers can inspect or retry the handle.

pub async fn close_without_checkpoint_in_place(&mut self) -> Result<()>

Close the connection in place without forcing a final WAL checkpoint.

This still rolls back or flushes transaction state and tears down runtime regions; it only skips the passive checkpoint that close() normally performs in WAL mode.

pub async fn close_best_effort_in_place(&mut self)

Close the connection using the same no-checkpoint best-effort shutdown path used by Drop, but mark it closed so dropping the handle is not reported as an API misuse.

pub fn register_collation_function<C>(&self, collation: C)

where C: CollationFunction + 'static,

Register a custom collation for subsequent prepares and executions.

Existing prepared statements are invalidated before a displaced collation is dropped, so cached comparison state cannot outlive a replacement. This also supplies dependencies referenced by persisted indexes that were intentionally left unresolved while opening the database.

pub fn register_deterministic_scalar_function<F>(&self, function: F)

where F: ScalarFunction + 'static,

Register a deterministic custom scalar function.

The function becomes available immediately for subsequent queries. Existing prepared statements invalidate and subsequently fail with FrankenError::SchemaChanged so stale cached function bindings cannot execute against the redefined registry.

Overwrites any existing function with the same (name, num_args) key.

pub fn register_nondeterministic_scalar_function<F>(&self, function: F)

where F: ScalarFunction + 'static,

Register a non-deterministic custom scalar function.

Non-deterministic functions remain available to ordinary SQL but are rejected from expression indexes and partial-index predicates.

pub fn register_aggregate_function<F>(&self, function: F)

where F: AggregateFunction + 'static, F::State: 'static,

Register a custom aggregate function.

The function becomes available immediately for subsequent queries. Existing prepared statements invalidate and subsequently fail with FrankenError::SchemaChanged so stale cached function bindings cannot execute against the redefined registry.

Overwrites any existing function with the same (name, num_args) key.

pub fn register_window_function<F>(&self, function: F)

where F: WindowFunction + 'static, F::State: 'static,

Register a custom window function.

The function becomes available immediately for subsequent queries. Existing prepared statements invalidate and subsequently fail with FrankenError::SchemaChanged so stale cached function bindings cannot execute against the redefined registry.

Overwrites any existing function with the same (name, num_args) key.

pub fn register_module(&self, name: &str, factory: Box<dyn VtabModuleFactory>)

Register a virtual-table module factory under the given name.

Once registered, CREATE VIRTUAL TABLE t USING name(args) will invoke the factory’s create method to instantiate the vtab. Existing prepared statements are invalidated so cached table-function metadata cannot outlive a module replacement.

pub fn register_rtree_geometry( &self, table_name: &str, geometry_name: &str, geometry: Box<dyn RtreeGeometry>, ) -> Result<()>

Register a custom geometry callback on a live SQL-created R-tree table.

pub async fn prepare(&self, sql: &str) -> Result<PreparedStatement<'_>>

Prepare SQL into a statement.

pub async fn query(&self, sql: &str) -> Result<Vec<Row>>

Prepare and execute SQL as a query.

When sql contains multiple statements, only the result rows from the last statement are returned. Intermediate statement results are discarded. This matches common SQL driver semantics (last statement wins).

pub async fn query_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<Vec<Row>>

Prepare and execute SQL as a query with bound SQL parameters.

pub async fn query_with_params_for_each<F>( &self, sql: &str, params: &[SqliteValue], f: F, ) -> Result<()>

where F: FnMut(&Row) -> Result<()>,

Prepare and execute SQL as a query with bound SQL parameters, invoking f for each row as it is produced.

pub async fn query_row(&self, sql: &str) -> Result<Row>

Prepare and execute SQL as a query, returning exactly one row.

pub async fn query_row_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<Row>

Prepare and execute SQL as a query with bound SQL parameters, returning exactly one row.

pub async fn execute(&self, sql: &str) -> Result<usize>

Prepare and execute SQL, returning output/affected row count.

For DML (INSERT/UPDATE/DELETE) this returns the number of affected rows. For SELECT and other statement types it returns the number of result rows.

pub async fn execute_batch(&self, sql: &str) -> Result<()>

Execute zero or more SQL statements separated by semicolons.

Empty batches and batches containing only whitespace, semicolons, or SQL comments are treated as a no-op, matching SQLite batch semantics.

pub async fn begin_transaction(&self) -> Result<()>

Begin a transaction without going through SQL parsing/dispatch.

This follows the same mode selection as plain BEGIN: explicit mode is absent, so concurrent_mode_default still controls whether the transaction auto-promotes to concurrent mode.

pub async fn commit_transaction(&self) -> Result<()>

Commit the active transaction without reparsing a COMMIT statement.

pub async fn rollback_transaction(&self) -> Result<()>

Roll back the active transaction without reparsing a ROLLBACK statement.

pub fn mark_transaction_cleanup_required(&self)

Record that a scoped transaction wrapper was dropped without an awaited commit() / rollback().

Drop::drop cannot await, and this crate never builds its own runtime, so a drop path cannot finish the rollback itself. It calls this instead to record the obligation; Self::settle_pending_transaction_cleanup discharges it at the next SQL entry point. The net effect is that an abandoned transaction’s writes are never observable to later statements, which is the contract rusqlite callers expect from rollback-on-drop, without blocking inside Drop.

pub async fn execute_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<usize>

Prepare and execute SQL with bound SQL parameters.

pub async fn execute_with_params_skip_statement_savepoint_in_explicit_txn( &self, sql: &str, params: &[SqliteValue], ) -> Result<usize>

Prepare and execute SQL with bound SQL parameters, skipping the internal statement savepoint when the call runs inside an explicit transaction.

This is a narrow performance escape hatch for callers that prevalidate statement inputs and treat the enclosing transaction as the rollback boundary. If execution fails inside an explicit transaction, callers must roll back that transaction to discard any partial effects. Outside an explicit transaction this behaves like execute_with_params.

pub async fn execute_many_with_params_skip_statement_savepoint_in_explicit_txn( &self, sql: &str, parameter_sets: &[Vec<SqliteValue>], ) -> Result<usize>

Prepare one statement once and execute every parameter set inside an explicit transaction without per-statement savepoints.

This is the batched counterpart to Self::execute_with_params_skip_statement_savepoint_in_explicit_txn. Callers must prevalidate application-level inputs and roll back the enclosing transaction if any execution fails; earlier effects remain pending in that transaction. Database constraints are still enforced by every execution.

pub async fn execute_prepared( &self, stmt: &PreparedStatement<'_>, ) -> Result<usize>

Execute a prepared DML statement (INSERT/UPDATE/DELETE) with no parameters.

pub async fn execute_prepared_with_params( &self, stmt: &PreparedStatement<'_>, params: &[SqliteValue], ) -> Result<usize>

Execute a prepared DML statement (INSERT/UPDATE/DELETE) with bound parameters.

pub fn clear_compilation_reuse_caches(&self)

Clear all prepared-statement / compiled-program / planner-directive caches on this connection and reset statement lookaside scratch buffers.

Intended to be called whenever cached plans may have become stale with respect to the schema, planner inputs, function registry, or committed row image. Write commits clear these caches because prepared execution templates may capture storage visibility assumptions, not just schema.

Historical context: before post-write execution invalidation was added, downstream callers (notably beads_rust) had to wrap re-read paths in CTEs to force dispatch through the uncached slow path. See issue #72.

impl Connection

pub fn in_transaction(&self) -> bool

Returns true if an explicit transaction is active.

pub fn is_concurrent_transaction(&self) -> bool

Returns true if the current transaction was started with BEGIN CONCURRENT (or was promoted to concurrent mode via the fsqlite.concurrent_mode PRAGMA).

pub fn is_concurrent_mode_default(&self) -> bool

Returns true if the connection-level concurrent-mode default is enabled (i.e. PRAGMA fsqlite.concurrent_mode = ON).

pub fn write_merge_mode(&self) -> WriteMergeMode

Returns the current commit-path safety regime (PRAGMA fsqlite.write_merge).

pub fn should_skip_ssi_validation(&self, force_audit_hash: u64) -> bool

Consults the anytime-valid e-process gate to decide whether the caller may skip full SSI validation for one commit.

Returns false unconditionally when write_merge_mode is Safe — the production-safe default. Returns the gate’s current decision otherwise. force_audit_hash should be any uniformly- distributed integer (e.g. the low bits of the commit sequence) so the gate can deterministically audit-sample a subset of commits.

See fsqlite_mvcc::SsiEProcessGate::should_skip_ssi for the mathematical details.

pub fn observe_ssi_outcome(&self, conflict_detected: bool)

Feeds one SSI outcome observation into the e-process. conflict_detected must be the real return of a ssi_validate_and_publish call (true iff it returned Err). Always safe to call regardless of write_merge_mode; the gate is simply unconsulted under Safe.

pub fn ssi_e_process_snapshot(&self) -> SsiEProcessSnapshot

Returns a diagnostic snapshot of the SSI e-process gate.

pub fn reset_ssi_e_process_gate(&self)

Resets the SSI e-process gate state on this connection. Useful when the caller detects a workload regime change (bulk DDL, schema change, long idle period).

pub fn has_concurrent_session(&self) -> bool

Returns true if there is an active MVCC concurrent session for this connection (bd-14zc / 5E.1).

pub fn concurrent_writer_count(&self) -> usize

Returns the number of active concurrent writers across all connections sharing this registry (bd-14zc / 5E.1).

pub fn ssi_decisions_snapshot(&self) -> Vec<SsiDecisionCard>

Returns a snapshot of retained SSI decision cards.

pub fn query_ssi_decisions( &self, query: &SsiDecisionQuery, ) -> Vec<SsiDecisionCard>

Query SSI decision cards by transaction id, decision type, and/or time range.

pub fn raptorq_repair_evidence_snapshot(&self) -> Vec<WalFecRepairEvidenceCard>

Returns a snapshot of retained RaptorQ repair evidence cards.

pub fn query_raptorq_repair_evidence_cards( &self, query: &WalFecRepairEvidenceQuery, ) -> Vec<WalFecRepairEvidenceCard>

Query RaptorQ repair evidence cards by page/frame, severity bucket, and/or time range.

pub fn pragma_state(&self) -> Ref<'_, ConnectionPragmaState>

Returns a reference to the connection-scoped PRAGMA state.

The harness uses this to verify that both engines received identical configuration (journal_mode, synchronous, cache_size, page_size, busy_timeout).

pub async fn register_differential_view_subscriber( &self, view_name: &str, sender: Sender<DifferentialEvent>, ) -> Result<u64>

Registers a connection-local differential subscriber for an existing view.

The subscriber receives a snapshot payload at the current committed CommitSeq(N) and will subsequently receive invalidation events beginning at N + 1 until table-level differential routing lands.

pub fn unregister_differential_subscriber(&self, subscriber_id: u64) -> bool

Removes a previously registered differential subscriber.

pub fn differential_subscribers(&self) -> Vec<DifferentialSubscriberStatus>

Returns a stable status snapshot of active differential subscribers.

pub fn differential_subscriber_count(&self) -> usize

Returns the number of active differential subscribers.

pub fn schema_cookie(&self) -> u32

Read the current schema cookie value.

pub fn schema_generation(&self) -> u64

pub fn compiled_cache_len(&self) -> usize

Number of entries in the compiled bytecode cache (bd-1dp9.6.7.2.2).

pub async fn change_counter(&self) -> u32

Read the current file change counter (database header offset 24).

For file-backed databases the authoritative value lives in page 1, which the pager rewrites (with version_valid_for kept in sync) whenever a committing write transaction touches page 1. We read it live through the pager so the result is WAL-aware: the main-file copy can lag until checkpoint, but the pager sees the WAL page-1 image. This matches C SQLite semantics — in rollback-journal mode the counter advances once per write transaction, while in WAL mode it only advances when page 1 itself is rewritten (DDL, page-count change). For :memory: databases there is no persistent header, so the cached counter (maintained by reload/VACUUM) is returned. (5D.4 / bd-lxm9j)

Trait Implementations

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.