pub struct ManagedConnection { /* private fields */ }Expand description
Logical SQLite session backed by a bounded physical connection pool.
Cloning preserves session/transaction affinity; call Self::new_session
for an independently isolated transaction context.
Implementations§
Source§impl ManagedConnection
impl ManagedConnection
Sourcepub fn database_path(&self) -> Option<&Path>
pub fn database_path(&self) -> Option<&Path>
Return the backing database path for a file-backed connection.
Source§impl ManagedConnection
impl ManagedConnection
Sourcepub fn new_session(&self) -> Self
pub fn new_session(&self) -> Self
Create an independent logical session over the same database pool. Explicit transactions started on either session are isolated and never capture operations issued through the other session.
Sourcepub fn new_session_with_cancellation(
&self,
cancellation: &CancellationToken,
) -> Self
pub fn new_session_with_cancellation( &self, cancellation: &CancellationToken, ) -> Self
Use a fresh transaction context while sharing the invoking execution’s write cancellation. Existing sessions and clones keep their original token.
Sourcepub fn write_cancellation(&self) -> CancellationToken
pub fn write_cancellation(&self) -> CancellationToken
Share the token used for autonomous allocation and record publication. Cleanup reads and rollback remain independent of this flag.
Sourcepub fn transaction_model(&self) -> StorageTransactionModel
pub fn transaction_model(&self) -> StorageTransactionModel
Transaction ownership selected for this connection and inherited by its independent sessions.
Sourcepub fn refresh_transaction_snapshot(
&self,
cancellation: &CancellationToken,
) -> Result<()>
pub fn refresh_transaction_snapshot( &self, cancellation: &CancellationToken, ) -> Result<()>
Advance a bound native or Key/Value command view through the common session, without opening a physical writer. Legacy physical transactions require their existing transaction boundary instead.
Sourcepub fn with_physical<R>(
&self,
operation: impl FnOnce(&Connection) -> Result<R>,
) -> Result<R>
pub fn with_physical<R>( &self, operation: impl FnOnce(&Connection) -> Result<R>, ) -> Result<R>
Access physical SQLite state for explicit diagnostics or maintenance outside any session transaction. This does not read private logical changes; ordinary stores must use their owning transaction interface. Record-table write guards remain active.
Source§impl ManagedConnection
impl ManagedConnection
Sourcepub fn bind_native_records(
&self,
options: VersionedSessionOptions,
) -> Result<()>
pub fn bind_native_records( &self, options: VersionedSessionOptions, ) -> Result<()>
Bind a new or existing native catalog or recognized standalone graph file to shared logical record transactions, initializing/upgrading and converting its physical format atomically if needed. Document/B-tree stores, exact/IVF/HNSW vectors, occurrences and catalog operations share this session. Native provider factories publish a legacy catalog restore and its baseline together before attaching this session; direct callers must bind before opening a catalog on an already converted file. Standalone graph handles retain their scoped records, including handles opened before binding. Direct physical access is rejected.
Source§impl ManagedConnection
impl ManagedConnection
Sourcepub fn open_restored(
path: &Path,
request: DatabaseRestore,
control: &StorageReadControl,
) -> Result<Self>
pub fn open_restored( path: &Path, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>
Restore an existing, closed consistent backup into the request’s new transaction-history incarnation. Persist the request outside the database first; retry that same request after any error. Intermediate durable states reject ordinary opens. All connections, sessions, snapshots and SSI participants must be released first. A completed retry preserves later work. The returned connection can be bound to its original native or Key/Value mapping.
Sourcepub fn open_encrypted_restored(
path: &Path,
key: &str,
request: DatabaseRestore,
control: &StorageReadControl,
) -> Result<Self>
pub fn open_encrypted_restored( path: &Path, key: &str, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>
SQLCipher counterpart of Self::open_restored, using the same credential for its SSI database.
Sourcepub fn open_compressed_restored(
path: &Path,
compression: SQLiteCompressionOptions,
request: DatabaseRestore,
control: &StorageReadControl,
) -> Result<Self>
pub fn open_compressed_restored( path: &Path, compression: SQLiteCompressionOptions, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>
Compressed-container counterpart of Self::open_restored.
Sourcepub fn open_compressed_encrypted_restored(
path: &Path,
key: &str,
compression: SQLiteCompressionOptions,
request: DatabaseRestore,
control: &StorageReadControl,
) -> Result<Self>
pub fn open_compressed_encrypted_restored( path: &Path, key: &str, compression: SQLiteCompressionOptions, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>
Encrypted compressed-container counterpart of Self::open_restored.
Sourcepub fn open_compressed_encrypted_restored_with_anchor(
path: &Path,
key: &str,
compression: SQLiteCompressionOptions,
trusted_anchor: SQLiteCompressedContainerAnchor,
request: DatabaseRestore,
control: &StorageReadControl,
) -> Result<Self>
pub fn open_compressed_encrypted_restored_with_anchor( path: &Path, key: &str, compression: SQLiteCompressionOptions, trusted_anchor: SQLiteCompressedContainerAnchor, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>
Enforce the caller’s trusted current container anchor before restoring. As with ordinary anchored opening, retain an updated anchor after a successful write; an old anchor cannot authorize a retry against a changed container.
Source§impl ManagedConnection
impl ManagedConnection
pub fn open(path: &Path) -> Result<Self>
Sourcepub fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey>
pub fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey>
Retain the database credential for encrypted auxiliary storage, including compressed containers whose main-file encryption lives in the VFS.
Sourcepub fn lease_connection(&self) -> Result<SQLiteConnectionLease>
pub fn lease_connection(&self) -> Result<SQLiteConnectionLease>
Lease an independent physical connection without joining this logical session’s transaction. The pool retains encryption and connection policy.
Sourcepub fn open_auxiliary(
path: &Path,
key: Option<StorageEncryptionKey>,
) -> Result<Self>
pub fn open_auxiliary( path: &Path, key: Option<StorageEncryptionKey>, ) -> Result<Self>
Open database-owned auxiliary storage with its inherited credential and original DELETE journaling. Concurrent first opens never change journal modes. An incompatible existing mode is rejected without rewriting it.
pub fn open_encrypted(path: &Path, key: &str) -> Result<Self>
pub fn open_compressed( path: &Path, compression: SQLiteCompressionOptions, ) -> Result<Self>
pub fn open_compressed_encrypted( path: &Path, key: &str, compression: SQLiteCompressionOptions, ) -> Result<Self>
Sourcepub fn open_compressed_encrypted_with_anchor(
path: &Path,
key: &str,
compression: SQLiteCompressionOptions,
trusted_anchor: SQLiteCompressedContainerAnchor,
) -> Result<Self>
pub fn open_compressed_encrypted_with_anchor( path: &Path, key: &str, compression: SQLiteCompressionOptions, trusted_anchor: SQLiteCompressedContainerAnchor, ) -> Result<Self>
Open an encrypted compressed database while enforcing an exact trusted external state anchor in the VFS main-file open path.
pub fn open_in_memory() -> Result<Self>
Sourcepub fn transaction_affinity(&self) -> StorageSessionAffinity
pub fn transaction_affinity(&self) -> StorageSessionAffinity
Identity shared by handles using this session’s native or logical transaction context.
Sourcepub fn in_transaction(&self) -> bool
pub fn in_transaction(&self) -> bool
Whether this session has an active native or logical record transaction.
Sourcepub fn transaction_has_written(&self) -> Result<bool>
pub fn transaction_has_written(&self) -> Result<bool>
Whether this session has staged writes, including private logical records. Callers use this to enforce read-only execution boundaries before COMMIT.
Sourcepub fn data_version_monitor_is_nonblocking(&self) -> Result<bool>
pub fn data_version_monitor_is_nonblocking(&self) -> Result<bool>
Whether this session’s independent Self::data_version monitor can
read without contending with the currently pinned transaction.
A rollback-journal writer’s pending lock blocks new readers while waiting for existing readers to finish. A rollback-journal read transaction must therefore also avoid the independent monitor: its own shared lock may be preventing that waiting writer from proceeding. Callers refresh through the pinned connection instead. WAL sessions and sessions without a pinned transaction permit the independent monitor.
Sourcepub fn supports_concurrent_pinned_read_and_write(&self) -> bool
pub fn supports_concurrent_pinned_read_and_write(&self) -> bool
Whether one pooled connection may retain a read snapshot while another writes. Ordinary plain and encrypted SQLite databases use WAL; compressed containers and auxiliary files use rollback journaling and therefore require a detached engine snapshot before writer promotion.
Sourcepub fn data_version(&self) -> Result<Option<u64>>
pub fn data_version(&self) -> Result<Option<u64>>
Database change counter observed on one stable connection shared by
every logical session over this pool. The value changes when another
SQLite connection commits. In-memory databases have no independent
connections and therefore return None.
Sourcepub fn pin_transaction_snapshot(&self) -> Result<()>
pub fn pin_transaction_snapshot(&self) -> Result<()>
Establish the database snapshot for the active transaction without
depending on the caller’s first user query. BEGIN DEFERRED alone does
not start a read transaction, so a writer could otherwise commit after
the engine checks its cache generations but before the first catalog
read. Reading sqlite_schema is database-wide and keeps the operation
independent of any application table.
Sourcepub fn with<R>(&self, f: impl FnOnce(&Connection) -> Result<R>) -> Result<R>
pub fn with<R>(&self, f: impl FnOnce(&Connection) -> Result<R>) -> Result<R>
Run a closure using this session. Outside a transaction the closure checks out a pooled connection; inside a transaction every clone is routed to the session’s pinned connection.
pub fn with_mut<R>( &self, f: impl FnOnce(&mut Connection) -> Result<R>, ) -> Result<R>
Sourcepub fn vacuum(&self) -> Result<()>
pub fn vacuum(&self) -> Result<()>
Rewrite the SQLite database into its minimum-sized file. SQLite requires VACUUM to run in autocommit mode, so the session write gate makes the transaction check and maintenance command one atomic session operation.
Sourcepub fn begin_transaction(&self) -> Result<()>
pub fn begin_transaction(&self) -> Result<()>
Open an explicit (non-deferred) transaction. Subsequent
auto-commit hosts (catalog writes, FTS index updates, …) all
flow through the same connection so the transaction enclosing
them is honoured. Use Self::commit_transaction /
Self::rollback_transaction / Self::savepoint etc. for
the lifecycle.
Sourcepub fn begin_deferred_transaction(&self) -> Result<()>
pub fn begin_deferred_transaction(&self) -> Result<()>
Open a deferred transaction. Read-only SQL statements use this mode
so WAL readers do not take the single writer reservation; if a scalar
routine performs a write, SQLite upgrades the same transaction and
still preserves the statement’s atomic boundary.