pub struct Connection { /* private fields */ }Expand description
A database connection holding schema metadata and execution/cache state.
Supports transactions (BEGIN/COMMIT/ROLLBACK) and savepoints
(SAVEPOINT/RELEASE/ROLLBACK TO). The default runtime path uses pager/WAL/B-tree
storage, while MemDatabase is retained as an execution image and limited
compatibility fallback.
Implementations§
Source§impl Connection
impl Connection
Sourcepub fn open(path: impl Into<String>) -> Result<Self>
pub 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.
Sourcepub fn open_schema_only(path: impl Into<String>) -> Result<Self>
pub 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")?;Sourcepub fn open_schema_only_with_env(
path: impl Into<String>,
env: ConnectionEnv,
) -> Result<Self>
pub 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.
Sourcepub fn open_with_env(
path: impl Into<String>,
env: ConnectionEnv,
) -> Result<Self>
pub 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.
Sourcepub fn background_status(&self) -> Result<()>
pub fn background_status(&self) -> Result<()>
Return the background-runtime health for this connection’s database.
Sourcepub fn set_reject_mem_fallback(&self, reject: bool)
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.
Sourcepub fn set_strict_mem_fallback_rejection(&self, strict: bool)
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.
Sourcepub fn pager_backend_kind(&self) -> &'static str
pub fn pager_backend_kind(&self) -> &'static str
Returns the kind of pager backend in use (e.g. “memory”, “iouring”, or “unix”).
Sourcepub fn validate_parity_cert_backend(&self) -> Result<(), String>
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.
Sourcepub fn last_local_commit_seq(&self) -> Option<u64>
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.
Sourcepub fn current_concurrent_snapshot_seq(&self) -> Option<u64>
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.
Sourcepub fn root_cx(&self) -> &Cx
pub fn root_cx(&self) -> &Cx
Returns a reference to the root capability context for this connection.
Sourcepub fn trace_v2(&self, mask: TraceMask, callback: Option<TraceCallback>)
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.
Sourcepub fn close(self) -> Result<()>
pub fn close(self) -> Result<()>
Close the connection and perform pager/WAL shutdown steps.
On close:
- Roll back any active transaction.
- Run a passive checkpoint (WAL -> DB).
- Mark the connection as closed so
Dropdoesn’t repeat cleanup.
Sourcepub fn close_in_place(&mut self) -> Result<()>
pub 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.
Sourcepub fn register_scalar_function<F>(&self, function: F)where
F: ScalarFunction + 'static,
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.
Previously prepared statements are NOT affected — only new
prepare() / query() / execute() calls see the new function.
Overwrites any existing function with the same (name, num_args) key.
Sourcepub fn register_aggregate_function<F>(&self, function: F)where
F: AggregateFunction + 'static,
F::State: 'static,
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.
Overwrites any existing function with the same (name, num_args) key.
Sourcepub fn register_window_function<F>(&self, function: F)where
F: WindowFunction + 'static,
F::State: 'static,
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.
Overwrites any existing function with the same (name, num_args) key.
Sourcepub fn register_module(&self, name: &str, factory: Box<dyn VtabModuleFactory>)
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.
Sourcepub fn register_rtree_geometry(
&self,
table_name: &str,
geometry_name: &str,
geometry: Box<dyn RtreeGeometry>,
) -> Result<()>
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.
Sourcepub fn prepare(&self, sql: &str) -> Result<PreparedStatement<'_>>
pub fn prepare(&self, sql: &str) -> Result<PreparedStatement<'_>>
Prepare SQL into a statement.
Sourcepub fn query(&self, sql: &str) -> Result<Vec<Row>>
pub 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).
Sourcepub fn query_with_params(
&self,
sql: &str,
params: &[SqliteValue],
) -> Result<Vec<Row>>
pub fn query_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<Vec<Row>>
Prepare and execute SQL as a query with bound SQL parameters.
Sourcepub fn query_row(&self, sql: &str) -> Result<Row>
pub fn query_row(&self, sql: &str) -> Result<Row>
Prepare and execute SQL as a query, returning exactly one row.
Sourcepub fn query_row_with_params(
&self,
sql: &str,
params: &[SqliteValue],
) -> Result<Row>
pub 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.
Sourcepub fn execute(&self, sql: &str) -> Result<usize>
pub 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.
Sourcepub fn execute_batch(&self, sql: &str) -> Result<()>
pub 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.
Sourcepub fn execute_with_params(
&self,
sql: &str,
params: &[SqliteValue],
) -> Result<usize>
pub fn execute_with_params( &self, sql: &str, params: &[SqliteValue], ) -> Result<usize>
Prepare and execute SQL with bound SQL parameters.
Sourcepub fn execute_prepared(&self, stmt: &PreparedStatement<'_>) -> Result<usize>
pub fn execute_prepared(&self, stmt: &PreparedStatement<'_>) -> Result<usize>
Execute a prepared DML statement (INSERT/UPDATE/DELETE) with no parameters.
Sourcepub fn execute_prepared_with_params(
&self,
stmt: &PreparedStatement<'_>,
params: &[SqliteValue],
) -> Result<usize>
pub fn execute_prepared_with_params( &self, stmt: &PreparedStatement<'_>, params: &[SqliteValue], ) -> Result<usize>
Execute a prepared DML statement (INSERT/UPDATE/DELETE) with bound parameters.
Sourcepub fn in_transaction(&self) -> bool
pub fn in_transaction(&self) -> bool
Returns true if an explicit transaction is active.
Sourcepub fn gc_enqueue_page(&self, pgno: PageNumber)
pub fn gc_enqueue_page(&self, pgno: PageNumber)
Enqueue a page for GC consideration after a version is published.
Called when a new version of a page is committed, making older versions potentially eligible for pruning.
Sourcepub fn is_concurrent_transaction(&self) -> bool
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).
Sourcepub fn is_concurrent_mode_default(&self) -> bool
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).
Sourcepub fn has_concurrent_session(&self) -> bool
pub fn has_concurrent_session(&self) -> bool
Returns true if there is an active MVCC concurrent session for this
connection (bd-14zc / 5E.1).
Sourcepub fn concurrent_writer_count(&self) -> usize
pub fn concurrent_writer_count(&self) -> usize
Returns the number of active concurrent writers across all connections sharing this registry (bd-14zc / 5E.1).
Sourcepub fn ssi_decisions_snapshot(&self) -> Vec<SsiDecisionCard>
pub fn ssi_decisions_snapshot(&self) -> Vec<SsiDecisionCard>
Returns a snapshot of retained SSI decision cards.
Sourcepub fn query_ssi_decisions(
&self,
query: &SsiDecisionQuery,
) -> Vec<SsiDecisionCard>
pub fn query_ssi_decisions( &self, query: &SsiDecisionQuery, ) -> Vec<SsiDecisionCard>
Query SSI decision cards by transaction id, decision type, and/or time range.
Sourcepub fn raptorq_repair_evidence_snapshot(&self) -> Vec<WalFecRepairEvidenceCard>
pub fn raptorq_repair_evidence_snapshot(&self) -> Vec<WalFecRepairEvidenceCard>
Returns a snapshot of retained RaptorQ repair evidence cards.
Sourcepub fn query_raptorq_repair_evidence_cards(
&self,
query: &WalFecRepairEvidenceQuery,
) -> Vec<WalFecRepairEvidenceCard>
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.
Sourcepub fn pragma_state(&self) -> Ref<'_, ConnectionPragmaState>
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).
Sourcepub fn register_differential_view_subscriber(
&self,
view_name: &str,
sender: Sender<DifferentialEvent>,
) -> Result<u64>
pub 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.
Sourcepub fn unregister_differential_subscriber(&self, subscriber_id: u64) -> bool
pub fn unregister_differential_subscriber(&self, subscriber_id: u64) -> bool
Removes a previously registered differential subscriber.
Sourcepub fn differential_subscribers(&self) -> Vec<DifferentialSubscriberStatus>
pub fn differential_subscribers(&self) -> Vec<DifferentialSubscriberStatus>
Returns a stable status snapshot of active differential subscribers.
Sourcepub fn differential_subscriber_count(&self) -> usize
pub fn differential_subscriber_count(&self) -> usize
Returns the number of active differential subscribers.
Read the current schema cookie value.
pub fn schema_generation(&self) -> u64
Sourcepub fn compiled_cache_len(&self) -> usize
pub fn compiled_cache_len(&self) -> usize
Number of entries in the compiled bytecode cache (bd-1dp9.6.7.2.2).
Sourcepub fn change_counter(&self) -> u32
pub fn change_counter(&self) -> u32
Read the current file change counter value.