Skip to main content

ManagedConnection

Struct ManagedConnection 

Source
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

Source

pub fn database_path(&self) -> Option<&Path>

Return the backing database path for a file-backed connection.

Source§

impl ManagedConnection

Source

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.

Source

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.

Source

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.

Source

pub fn transaction_model(&self) -> StorageTransactionModel

Transaction ownership selected for this connection and inherited by its independent sessions.

Source

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.

Source

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

Source

pub fn prune_diskann_changes( &self, source: &RetainedSQLiteDiskANNCanonical, resolver: &dyn DiskANNIndexResolver, pruner: &KeyValueDiskANNPruner, request: DiskANNPruneRequest, control: &StorageReadControl, ) -> StorageBackendResult<DiskANNPruneResult>

Prune one bounded DiskANN journal page in this connection’s evaluated transaction. The captured source guards the catalog; the current committed canonical view and selected physical coverage determine deletion. Advance the returned cursor only after committing the caller’s transaction.

Source

pub fn publish_diskann_generation( &self, coverage: &DiskANNCanonicalCoverage<RetainedSQLiteDiskANNCanonical>, resolver: &dyn DiskANNIndexResolver, control: &StorageReadControl, ) -> StorageBackendResult<()>

Install an actually sealed DiskANN generation and its complete coverage in this connection’s native transaction. The build’s retained source supplies catalog and expected-head evidence. Later private DDL must cancel or supersede this effect through the catalog lifecycle owner.

Source

pub fn diskann_generations( &self, control: &StorageReadControl, ) -> StorageBackendResult<KeyValueDiskANNStore>

Connect physical DiskANN staging to an already bound native owner. The returned store opens a dedicated session; it cannot complete this connection’s transaction or publish a SQL index.

Source

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

Source

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.

Source

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.

Source

pub fn open_compressed_restored( path: &Path, compression: SQLiteCompressionOptions, request: DatabaseRestore, control: &StorageReadControl, ) -> Result<Self>

Compressed-container counterpart of Self::open_restored.

Source

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.

Source

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

Source

pub fn open(path: &Path) -> Result<Self>

Source

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.

Source

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.

Source

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.

Source

pub fn open_encrypted(path: &Path, key: &str) -> Result<Self>

Source

pub fn open_compressed( path: &Path, compression: SQLiteCompressionOptions, ) -> Result<Self>

Source

pub fn open_compressed_encrypted( path: &Path, key: &str, compression: SQLiteCompressionOptions, ) -> Result<Self>

Source

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.

Source

pub fn open_in_memory() -> Result<Self>

Source

pub fn transaction_affinity(&self) -> StorageSessionAffinity

Identity shared by handles using this session’s native or logical transaction context.

Source

pub fn in_transaction(&self) -> bool

Whether this session has an active native or logical record transaction.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn with_mut<R>( &self, f: impl FnOnce(&mut Connection) -> Result<R>, ) -> Result<R>

Source

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.

Source

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

Reclaim obsolete logical records and history without executing a physical SQLite VACUUM.

Source

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.

Source

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.

Source

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

Source

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

Source

pub fn savepoint(&self, name: &str) -> Result<()>

Source

pub fn release_savepoint(&self, name: &str) -> Result<()>

Source

pub fn rollback_to_savepoint(&self, name: &str) -> Result<()>

Trait Implementations§

Source§

impl Clone for ManagedConnection

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl NotificationPublicationStore for ManagedConnection

Source§

fn stage_notification_publication( &self, publication: &NotificationPublication, ) -> StorageBackendResult<()>

Source§

fn stage_notification_publication_after( &self, publication: &NotificationPublication, acknowledged: Option<[u8; 32]>, ) -> StorageBackendResult<()>

Replace a previous slot only when the registry has already committed that exact acknowledgement. Serialized physical writers may need to carry this cleanup in their own atomic data transaction; the default requires autonomous cleanup first.
Source§

fn visit_notification_publication( &self, control: &StorageReadControl, visit: &mut dyn FnMut(Option<NotificationPublicationView<'_>>) -> StorageBackendResult<()>, ) -> StorageBackendResult<()>

Source§

fn acknowledge_notification_publication( &self, fingerprint: [u8; 32], control: &StorageReadControl, ) -> StorageBackendResult<()>

Clear only the acknowledged fingerprint through autonomous committed state. The caller must serialize queue acknowledgement and new publication and supply uncancelled completion control.
Source§

fn try_acknowledge_notification_publication( &self, fingerprint: [u8; 32], control: &StorageReadControl, ) -> StorageBackendResult<bool>

Return false when an existing physical writer prevents autonomous cleanup. The registry acknowledgement remains authoritative, and a later publisher may replace only that acknowledged fingerprint.
Source§

impl SerializableSession for ManagedConnection

Source§

fn establish_serializable_snapshot( &self, ) -> StorageBackendResult<SerializableReadContext>

Source§

fn establish_serializable_snapshot_with( &self, options: SerializableSnapshotOptions, capture: &mut SerializableSnapshotCapture<'_>, ) -> StorageBackendResult<SerializableReadContext>

Select the first snapshot using logical characteristics and a caller-scoped capture. Existing participants retain their original classification without another capture. Only read-only deferrable admission waits for a proven safe snapshot.
Source§

fn serializable_read_context( &self, ) -> StorageBackendResult<Option<SerializableReadContext>>

Source§

fn observe_serializable_write( &self, predicate: SerializablePredicate<'_>, ) -> StorageBackendResult<()>

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.