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 async fn capture_database_image_receipt( &self, ) -> Result<DatabaseImageReceipt>

Capture an identity- and content-bound receipt for the current durable main-database image.

Capture is the first half of full-image publication. Callers must retain the returned receipt while constructing a private replacement image and pass the same receipt to the publication surface. Publication then performs a full-image compare-and-swap against this exact source generation. A peer commit, journal-mode transition, or any other source change after capture causes publication to fail before it can commit.

The connection must be file-backed and outside every explicit transaction or savepoint. In WAL mode this method checkpoints and truncates the WAL before capturing the receipt so the token describes a self-contained main-file generation.

Errors

Returns FrankenError::Unsupported for a memory-backed connection, FrankenError::Busy when a transaction, savepoint, or live virtual-table transaction is open, and any propagated checkpoint or pager error.

pub fn reserve_schema_only_builder_target( path: impl AsRef<Path>, ) -> Result<DatabaseBuilderReservation>

Atomically claim a pathname for a replacement image and retain the descriptor that created it.

Phase 1 of the two-phase build protocol; see DatabaseBuilderReservation for why the returned value must be held across the whole build.

Errors

FrankenError::CannotOpen when the path is empty, is :memory:, or already names anything at all — existing regular files, hard links, directories, FIFOs, and live or dangling symlinks are refused without being opened, truncated, replaced, or unlinked. FrankenError::Unsupported on non-native builds.

pub fn reserve_schema_only_builder_target_with_env( path: impl AsRef<Path>, env: &ConnectionEnv, ) -> Result<DatabaseBuilderReservation>

Environment-bound form of Self::reserve_schema_only_builder_target.

The environment’s write-set page limit is validated here rather than at phase 2, so a caller learns it forgot the mandatory ceiling before it has claimed a pathname.

Errors

Everything Self::reserve_schema_only_builder_target returns, plus the refusals from ConnectionEnv::validated_schema_only_write_set_page_limit.

pub async fn initialize_reserved_schema_only_builder( reservation: &DatabaseBuilderReservation, env: ConnectionEnv, ) -> Result<Self>

Initialize a reserved target and return its identity-bound writable schema-only builder.

Phase 2. On the first call, revalidates the reservation at expected_len = Some(0), confirms the stable path still resolves to the reserved pathname, bootstraps page 1, and reopens that exact identity through the existing-file writable schema-only path with the validated write-set ceiling installed before return. Once the reserved opener has returned successfully, later calls are idempotent bounded reopens. This makes a close or post-bootstrap reopen failure safely retryable without admitting a file that was nonempty before the first initialization.

This specialized builder bootstrap keeps page 1 in rollback format and does not install a WAL backend. That is narrower than the ordinary and public reserved-open policy, which keeps WAL as the new-file default. The distinction prevents initialization alone from manufacturing a companion that a later self-contained bounded reopen must refuse.

Errors

FrankenError::CannotOpen when revalidation fails or the reserved path no longer resolves to itself or a prior ambiguous partial bootstrap poisoned initialization, FrankenError::Busy while another initialization owns the bootstrap phase, the refusals from ConnectionEnv::validated_schema_only_write_set_page_limit, and any propagated open error.

pub async fn reopen_reserved_schema_only_bounded_writer( reservation: &DatabaseBuilderReservation, env: ConnectionEnv, ) -> Result<Self>

Reopen a reserved database image as an identity-bound, existing-only, writable schema connection with its original write-set ceiling.

The borrowed DatabaseBuilderReservation is the sole pathname, identity, and limit authority. The environment must repeat the same explicit nonzero ceiling; absence, zero, or drift is refused before any database opener runs. The reservation must already have completed its identity-bound bootstrap phase; fresh, poisoned, or concurrently initializing reservations cannot bypass that phase through this API. The retained descriptor and the no-follow pathname are then revalidated before the exact-identity existing-only schema path is opened. The ceiling is installed on the pager before the connection is returned, so callers cannot observe an unbounded writer.

A rollback-header image (read_version == write_version == 1) receives a read-only preflight that refuses already-present recovery or WAL artifacts before opener handoff. The scan does not hold the namespace lock, so callers must still preserve the cooperative namespace through the open. A WAL-header image (2, 2) necessarily reopens its cooperative WAL family: the reservation authenticates the main-file pathname and identity, but does not independently authenticate companion contents. A caller that requires independent WAL provenance must bind or receipt that family separately.

Other environment settings, including caller-rooted runtime context, strict multi-process refusal, and page_buffer_max, retain their normal meanings. page_buffer_max remains independent of the write-set limit. Ordinary existing-schema opens remain unbounded even if their environment happens to carry this reserved-writer setting.

Errors

Returns the explicit-limit refusals from ConnectionEnv::validated_schema_only_write_set_page_limit, FrankenError::OutOfRange when the limit differs from the retained reservation, FrankenError::CannotOpen when the reservation is not safely bootstrapped, identity/stable-path validation fails, or a rollback-header image has a companion artifact, and any propagated open or pager error. On Unix, the identity validation also enforces a single link; Windows does not promise a link-count check.

pub async fn inspect_self_contained_image_receipt( &self, image_path: impl AsRef<Path>, ) -> Result<DatabaseImageReceipt>

Receipt an image at image_path without opening a connection on it.

Self::capture_database_image_receipt receipts the image this connection is already open on. That is the wrong tool for a candidate a caller has just built and intends to publish: receipting it would mean opening a handle on the very file whose byte-for-byte stillness is the thing being certified. This reads it through the pager instead, so the candidate keeps exactly one writer — the process that built it — and acquires no companion files from a bookkeeping open.

The image must be self-contained: no -wal, -shm, or -journal sibling. That is the same admission rule the publication and bounded snapshot surfaces apply, so a receipt obtained here is a receipt those surfaces will accept.

Errors

Returns FrankenError::Unsupported for a memory-backed connection, FrankenError::DatabaseCorrupt when image_path carries a companion file, and any propagated pager error.

pub async fn inspect_image_receipt( &self, image_path: impl AsRef<Path>, ) -> Result<DatabaseImageReceipt>

Receipt an image at image_path without requiring it to be self-contained.

Use this to observe an image that may still carry companions — for diagnostics, or to compare an image before and after an operation. The publication and bounded-snapshot surfaces will not accept a receipt for an image they would themselves refuse, so prefer Self::inspect_self_contained_image_receipt when the goal is to publish or validate.

Errors

Returns FrankenError::Unsupported for a memory-backed connection and any propagated pager error.

pub async fn validate_database_integrity_bounded( &self, spool_parent: &Path, ) -> Result<BoundedDatabaseValidationStats>

Prove an image’s structure AND its table/index/foreign-key semantic concordance, at fixed residency, inside one pinned transaction.

This is the full bounded validation: the structural ownership proof plus recomputed table rows, index concordance by bounded rescan and exact point probes, and declared foreign keys resolved fail-closed one child row at a time. The returned BoundedDatabaseValidationStats contains the structural stats rather than sitting beside them, so a caller reads one value for both.

The schema must first pass the admission gate; unsupported shapes and expressions are refused with FrankenError::NotImplemented rather than validated incompletely.

Errors

FrankenError::NotImplemented for an inadmissible schema, FrankenError::DatabaseCorrupt for a concordance failure, and any propagated pager error.

pub async fn validate_database_structure_bounded( &self, spool_parent: impl AsRef<Path>, ) -> Result<BoundedDatabaseStructuralStats>

Prove exact page ownership for this connection’s image with fixed resident memory.

Runs inside one read transaction and mutates neither the image nor this connection. spool_parent names the directory that will hold the anonymous ownership spool — one byte per database page, unlinked at creation, so it never appears in the directory and cannot outlive the call. It must be a real directory, not a symlink.

This proves structure only: page ownership, freelist accounting, and orphan detection. It performs no table/index semantic concordance.

Errors

Returns FrankenError::DatabaseCorrupt for duplicate ownership, cycles, out-of-range references, or orphan pages; FrankenError::NotImplemented for an image shape this validator does not admit (non-DELETE journal mode, or a schema above the fixed table ceiling); and any propagated pager error.

pub async fn begin_bounded_structural_snapshot<'a>( &'a self, expected: &DatabaseImageReceipt, image_path: impl AsRef<Path>, validation_page_limit: usize, ) -> Result<BoundedStructuralSnapshot<'a>>

Open a structurally-proven, receipt-bound snapshot of an external image.

This is the read side of full-image publication. It checks that image_path still matches expected, opens that exact file identity physically read-only, pins one deferred transaction, proves complete structural page ownership inside it, and hands back a guard holding all of it open. Every read the caller needs from the proven snapshot must go through BoundedStructuralSnapshot::connection; opening the path separately would leave the snapshot.

The caller must end the snapshot with BoundedStructuralSnapshot::finish, which releases the transaction and then proves the image is still byte-for-byte equal to expected. That final compare-and-swap is what makes a candidate built from this snapshot safe to publish; dropping the guard instead skips it and the result must not be trusted.

validation_page_limit caps the validation connection’s page buffer. Note that the cross-process page-limit fence is not yet restored on this line, so this bounds local residency, not concurrent writers; the receipt CAS above and below the window is what detects interference.

Errors

Returns FrankenError::OutOfRange for a zero page limit, FrankenError::Unsupported for a memory-backed source, FrankenError::BusySnapshot when the image no longer matches expected, and any propagated open or validation error.

pub async fn begin_database_image_publication<'a>( &'a self, source: &DatabaseImageReceipt, expected_candidate: &DatabaseImageReceipt, candidate_path: impl AsRef<Path>, ) -> Result<PendingDatabaseImagePublication<'a>>

Begin a whole-image publication and stop just before its commit point.

This is the write side of full-image replacement, and the mirror of Self::begin_bounded_structural_snapshot. It proves the source is still exactly source and the candidate still exactly expected_candidate, quiesces this connection, installs source-derived change-counter provenance on the candidate, reopens the candidate identity-bound and read-only, runs quick_check and integrity_check on it, and hands back a guard pinning that state.

The caller then runs whatever application-level checks it needs through PendingDatabaseImagePublication::candidate and finishes with PendingDatabaseImagePublication::commit to cross the commit point or PendingDatabaseImagePublication::abandon to refuse. abandon also restores the candidate’s exact provisional header counters, so a refused candidate is left byte-identical to what the caller handed in. Dropping the guard does neither: the reader is released, but the candidate keeps source-derived counters and no longer matches its own receipt, so a later attempt fails closed rather than publishing something unproven. That path logs an error.

Nothing here is durable for the source database. Every failure before commit leaves the source untouched.

Errors

Returns FrankenError::Unsupported for a memory-backed connection, FrankenError::Busy when a transaction, savepoint, or live virtual-table transaction is open, FrankenError::BusySnapshot when either image changed after its receipt was captured, FrankenError::CannotOpen when the candidate names the source itself, FrankenError::DatabaseCorrupt when the candidate fails its pre-publication integrity checks, and any propagated pager error.

pub async fn begin_bounded_database_image_publication<'a>( &'a self, source: &DatabaseImageReceipt, expected_candidate: &DatabaseImageReceipt, candidate_path: impl AsRef<Path>, validation_page_limit: usize, ) -> Result<PendingDatabaseImagePublication<'a>>

Begin a publication that additionally proves the candidate’s complete page ownership at bounded residency.

The bounded counterpart of Self::begin_bounded_structural_snapshot, and the reason the publish side is not weaker than the read side: the candidate handle is opened under a validation_page_limit page-buffer ceiling, one deferred transaction is pinned on it, and complete structural page ownership is proven inside that transaction before the caller sees the guard. The resulting BoundedDatabaseStructuralStats is available from PendingDatabaseImagePublication::structural_stats, so a caller can both bound the proof and assert afterwards what it cost.

The caller’s own reads run inside that same pinned transaction, so no writer can cross a snapshot generation between the proof and those reads.

This proves structure: page ownership, freelist accounting, and orphan detection. It performs no table/index semantic concordance — that validator has not been forward-ported yet, and this method deliberately does not pretend otherwise.

Errors

Everything Self::begin_database_image_publication returns, plus FrankenError::OutOfRange for a zero page limit and any structural validation error.

pub async fn publish_database_image_from_receipt<F>( &self, source: &DatabaseImageReceipt, expected_candidate: &DatabaseImageReceipt, candidate_path: impl AsRef<Path>, validate: F, ) -> Result<DatabaseImagePublication>

where F: AsyncFnOnce(&Self) -> Result<()>,

Publish an already-receipted private image, validating it with a caller callback that runs on a read-only, identity-bound handle.

Convenience over Self::begin_database_image_publication that guarantees the refusal path: if validate returns an error, the candidate’s provisional header counters are restored before that error is surfaced.

Errors

Everything Self::begin_database_image_publication and PendingDatabaseImagePublication::commit can return, plus whatever validate returns.

pub async fn publish_database_image_from_receipt_with_bounded_structural_validation<F>( &self, source: &DatabaseImageReceipt, expected_candidate: &DatabaseImageReceipt, candidate_path: impl AsRef<Path>, validation_page_limit: usize, validate: F, ) -> Result<DatabaseImagePublication>

where F: AsyncFnOnce(&Self, &BoundedDatabaseStructuralStats) -> Result<()>,

Publish an already-receipted candidate, proving its complete page ownership at bounded residency and handing the caller that proof.

The publish-side counterpart of Self::begin_bounded_structural_snapshot: validate runs inside the same pinned transaction the proof ran in, and receives the proof counters so a downstream certifier can assert after the fact what the validation actually cost rather than only what it configured.

Structural proof only — no table/index semantic concordance. See Self::begin_bounded_database_image_publication.

Errors

Everything Self::begin_bounded_database_image_publication and PendingDatabaseImagePublication::commit can return, plus whatever validate returns. A validate error restores the candidate’s exact provisional bytes before surfacing.

pub async fn publish_database_image_from_receipt_with_bounded_validation<F>( &self, source: &DatabaseImageReceipt, expected_candidate: &DatabaseImageReceipt, candidate_path: impl AsRef<Path>, validation_page_limit: usize, validate: F, ) -> Result<DatabaseImagePublication>

where F: AsyncFnOnce(&Self, &BoundedDatabaseValidationStats) -> Result<()>,

Publish an already-receipted candidate, proving its complete structure and its table/index/foreign-key semantic concordance at bounded residency, and handing the caller that proof.

This is the full guarantee, and the distinction from Self::publish_database_image_from_receipt_with_bounded_structural_validation is not cosmetic. The structural form proves page ownership, freelist accounting and orphan detection — it says the image is well-formed. This form additionally recomputes every table row, reconciles every index by bounded rescan and exact point probes, and resolves every declared foreign key one child row at a time. An image can pass the structural proof and fail here: a row missing from an index, or a foreign key pointing at a deleted parent, is structurally perfect and semantically wrong.

validate runs inside the same pinned transaction the proof ran in and receives BoundedDatabaseValidationStats, which contains the structural stats rather than sitting beside them.

Errors

FrankenError::NotImplemented when the candidate’s schema is outside the admitted fragment, FrankenError::DatabaseCorrupt for a concordance failure, everything Self::begin_bounded_database_image_publication and PendingDatabaseImagePublication::commit return, plus whatever validate returns. A refusal restores the candidate’s exact provisional bytes before surfacing.

pub fn write_set_stats(&self) -> Result<Option<WriteSetStats>>

Dirty-write-set accounting since the write-set ceiling was installed, when one is in force.

The high-water fields are window-wide maxima of each transaction’s live dirty-set cardinality. They deliberately do not sum or union pages from separate autocommit transactions.

Distinct from Self::page_cache_peak_snapshot, and the distinction is the whole point: residency answers “how many pages were held in memory”, which is a memory bound. This answers “how much of the database did the transaction actually rewrite”, which is what a bounded-migration certifier needs and what a residency peak cannot substitute for.

None when no ceiling is configured — reporting zeroes there would read as “nothing was written” rather than “nothing was bounded”.

Errors

Propagates pager errors.

pub fn page_cache_peak_snapshot(&self) -> Result<PageCachePeakSnapshot>

High-water page-cache residency reached on this connection.

Self::memory_stats reports instantaneous gauges, which let a caller assert the ceiling it configured but not that the ceiling was never approached. This reports the maximum residency actually reached, which is the assertion a bounded-operation certifier needs after the fact.

Read PageCachePeakSnapshot::exact before trusting the number: when it is false the peak is a sampled lower bound, and PageCachePeakSnapshot::proves_ceiling_never_approached returns None rather than a boolean.

Errors

Propagates pager errors.

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

Begin a new high-water measurement window.

Call immediately before a bounded operation so the peak read afterwards describes that operation rather than the connection’s whole history.

Errors

Propagates pager errors.

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 async fn repair_orphaned_pages(&self) -> Result<usize>

bd-84rh4: reachability-based freelist-hole repair. Frees any in-range page reachable from neither a b-tree (walked from sqlite_master) nor the durable freelist — the “Page N is never used” orphan class caused by a free (or abandoned EOF reservation) that never reached the durable freelist.

The caller MUST run this at a quiescent point (no concurrent writers): it enumerates holes in a read snapshot, then re-frees them through a normal write commit (the correct serialize_freelist_to_write_set publication path — never a hand-rolled trunk write). It adds NO writer-blocking contention (it is a maintenance-time commit) and is double-grant-safe by construction: “hole” is exactly integrity_check’s not-reachable-and-not-free definition, so a live page is never freed.

Auto-vacuum images are skipped: their pointer-map pages are not marked by this ownership walk, so enumerating orphans would be unsafe (this matches integrity_check, which skips its orphan scan for auto-vacuum images). Returns the number of pages re-freed.

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)

pub fn schema_reload_parse_count(&self) -> u64

bd-420r8 (GH#345): number of ACTUAL stored-schema statement parses (cache misses) the memdb reload path has performed on this connection. Exposed for the GH#345 regression keeper, which asserts it stays O(schema objects) across an ingestion burst instead of scaling with the row count. Per-connection (unlike the process-global metric counters), so it is not polluted by other tests sharing the process.

pub fn memdb_row_hydration_count(&self) -> u64

bd-qteu2 (GH#345 residual): number of user-table rows this connection has hydrated into the MemDatabase mirror via the memdb reload row-scan loop. Exposed for the qteu2 regression keeper, which asserts it stays sub-quadratic (O(total_rows + writes)) across an ingestion burst instead of O(writes × total_rows). Per-connection (unlike the process-global metric counters), so it is not polluted by other tests sharing the process.

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.