Struct SendFrankenConnection 

pub struct SendFrankenConnection(/* private fields */);

Wrapper around FrankenConnection that implements Send.

FrankenConnection is !Send because it uses Rc internally. However, the Rc values are entirely self-contained within the Connection and are not shared externally. When wrapped in a Mutex, exclusive access is guaranteed, making cross-thread transfer safe.

Methods from Deref<Target = FrankenConnection>

pub fn path(&self) -> &str

Returns the configured database path.

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

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

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

Snapshot current connection memory usage and page-cache state.

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

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 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 trace_v2( &self, mask: TraceMask, callback: Option<Arc<dyn Fn(TraceEvent) + Send + Sync>>, )

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 fn register_scalar_function<F>(&self, function: F)

where F: ScalarFunction + 'static,

Register a 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_aggregate_function<F>(&self, function: F)

where F: AggregateFunction + 'static, <F as AggregateFunction>::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 as WindowFunction>::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.

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

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

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

Prepare SQL into a statement.

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

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 fn query_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<Vec<Row>, FrankenError>

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

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

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

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

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

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

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

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

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

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 fn execute_batch(&self, sql: &str) -> Result<(), FrankenError>

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 fn begin_transaction(&self) -> Result<(), FrankenError>

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 fn commit_transaction(&self) -> Result<(), FrankenError>

Commit the active transaction without reparsing a COMMIT statement.

pub fn rollback_transaction(&self) -> Result<(), FrankenError>

Roll back the active transaction without reparsing a ROLLBACK statement.

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

Prepare and execute SQL with bound SQL parameters.

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

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

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

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.

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 fn register_differential_view_subscriber( &self, view_name: &str, sender: Sender<DifferentialEvent>, ) -> Result<u64, FrankenError>

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 fn change_counter(&self) -> u32

Read the current file change counter value.

Trait Implementations

impl Deref for SendFrankenConnection

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &FrankenConnection

Dereferences the value.

impl Send for SendFrankenConnection