pub struct ConnectionPool { /* private fields */ }Expand description
A read-write connection pool for SQLite.
Architecture:
- 1 writer connection protected by a Mutex (exclusive access)
- N reader connections in a lock-free queue (concurrent access)
- All connections share the same database file in WAL mode
Writable in-memory databases, or writable file databases when WAL mode is disabled/unavailable, degrade to single-connection mode and route all operations through the writer connection. A file-backed read-only pool always retains at least one dedicated read-only connection: rollback-journal snapshots do not need WAL to support concurrent readers, and inspection must never alias a read onto the query-only writer slot.
Implementations§
Source§impl ConnectionPool
impl ConnectionPool
Sourcepub fn reader(&self) -> Result<ReaderGuard<'_>, SqliteError>
pub fn reader(&self) -> Result<ReaderGuard<'_>, SqliteError>
Check out a reader connection.
Tries to pop from the lock-free queue. If empty, spins briefly then
waits with exponential backoff up to checkout_timeout.
In degraded mode (WAL unavailable, max_readers == 0), this method
checks the shared writer mutex in bounded slices and returns pool
exhaustion after checkout_timeout; it never blocks indefinitely on
the non-reentrant mutex.
Sourcepub fn writer(&self) -> Result<WriterGuard<'_>, SqliteError>
pub fn writer(&self) -> Result<WriterGuard<'_>, SqliteError>
Check out the writer connection.
Waits up to checkout_timeout for the writer Mutex and returns
Err(SqliteError::WriterPoolCheckoutTimeout) if the timeout is
exceeded.
Checkout owns exclusion, not a capacity sample. Consume the returned
guard with WriterGuard::autocommit or WriterGuard::transaction;
those operations sample at execution and retain ownership through
settlement. Raw connection access is crate-private.
Sourcepub fn try_writer(&self) -> Result<WriterGuard<'_>, SqliteError>
pub fn try_writer(&self) -> Result<WriterGuard<'_>, SqliteError>
Non-panicking writer checkout.
Returns Err on timeout instead of panicking. Use this in request
handlers where a 500 is preferable to crashing the process.
Sourcepub fn try_checkpoint_nowait(&self) -> Result<CheckpointGuard<'_>, SqliteError>
pub fn try_checkpoint_nowait(&self) -> Result<CheckpointGuard<'_>, SqliteError>
Zero-wait checkpoint checkout for recovery maintenance.
Uses try_lock() (no timeout, no spin) — returns Err immediately when
any other caller holds the writer Mutex. The scheduled checkpoint task
uses its own dedicated connection (ADR-091 Amendment 5); this optional
pooled capability remains available for zero-wait recovery callers.
It bypasses the disk-reserve floor because checkpoints can recover WAL space at or below that floor (ADR-154 §5). The returned guard exposes only fixed PASSIVE and TRUNCATE checkpoint operations.
The former unrestricted checkout must not return:
use khive_db::{ConnectionPool, PoolConfig};
let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
pool.try_writer_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");Source§impl ConnectionPool
impl ConnectionPool
Sourcepub fn new(config: PoolConfig) -> Result<Self, SqliteError>
pub fn new(config: PoolConfig) -> Result<Self, SqliteError>
Create a new connection pool.
Opens 1 writer + N reader connections to the same database when pooling is enabled. All connections are configured consistently (busy timeout, foreign keys, cache, mmap, temp store). Writable in-memory databases and writable non-WAL files fall back to single-connection mode. Read-only files retain a dedicated reader regardless of journal mode.
Source§impl ConnectionPool
impl ConnectionPool
Sourcepub fn record_note_search_ann_route(&self)
pub fn record_note_search_ann_route(&self)
Record an ANN route on the actual opened backend serving note search.
Sourcepub fn record_note_search_fallback_route(&self, cause: NoteSearchFallbackCause)
pub fn record_note_search_fallback_route(&self, cause: NoteSearchFallbackCause)
Record one exact fallback route and its cause on this opened backend.
Sourcepub fn note_search_route_snapshot(&self) -> NoteSearchRouteSnapshot
pub fn note_search_route_snapshot(&self) -> NoteSearchRouteSnapshot
Snapshot this pool’s note-search route counters without resetting them.
Source§impl ConnectionPool
impl ConnectionPool
Sourcepub fn writer_acquisition_snapshot(&self) -> WriterAcquisitionSnapshot
pub fn writer_acquisition_snapshot(&self) -> WriterAcquisitionSnapshot
Snapshot all instrumented writer acquisition outcomes since this pool was constructed.
Sourcepub fn record_search_dispatch(&self, backend_id: &str, requested_kind: &str)
pub fn record_search_dispatch(&self, backend_id: &str, requested_kind: &str)
Count a coordinator call only after served-kind filtering selects this backend. The canonical requested kind is the granular kind when one was supplied, or the entity/note substrate otherwise.
Sourcepub fn record_note_candidate_hydration_row(&self)
pub fn record_note_candidate_hydration_row(&self)
Count one actual candidate note row returned at the post-fusion hydration seam, including rows later filtered as deleted. Absent rows and later result metadata are excluded.
Sourcepub fn search_mechanism_snapshot(&self) -> SearchMechanismSnapshot
pub fn search_mechanism_snapshot(&self) -> SearchMechanismSnapshot
Snapshot ADR-166 G4/G5 counters. Values reset only with this pool.
Sourcepub fn reader_acquisition_snapshot(&self) -> ReaderAcquisitionSnapshot
pub fn reader_acquisition_snapshot(&self) -> ReaderAcquisitionSnapshot
Snapshot reader acquisition, saturation, and hold lifecycle outcomes since this pool was constructed. Counters reset only with pool reconstruction.
pub fn effective_disk_guard_config(&self) -> Option<EffectiveDiskGuardConfig>
Sourcepub fn available_readers(&self) -> usize
pub fn available_readers(&self) -> usize
Get the current number of available reader connections.
Sourcepub fn max_readers(&self) -> usize
pub fn max_readers(&self) -> usize
Get the total number of reader connections in the pool.
Sourcepub fn oldest_checkout_age(&self) -> Option<Duration>
pub fn oldest_checkout_age(&self) -> Option<Duration>
Age of the oldest outstanding pooled reader checkout, including
degraded shared-reader leases and their reset/replacement work.
Returns None when no checkout remains; standalone readers are
separately tracked by the transaction registry.
Sourcepub fn config(&self) -> &PoolConfig
pub fn config(&self) -> &PoolConfig
Return the pool configuration.
Sourcepub fn main_pool_generation(&self) -> u64
pub fn main_pool_generation(&self) -> u64
Identify this pool’s counter window when it is designated as main. Repeated runtime handles and diagnostics reads reuse the same generation; constructing secondary pools does not consume main-pool generations.
Sourcepub fn retirement_writer_holds(&self) -> usize
pub fn retirement_writer_holds(&self) -> usize
Current writer holds that prevent voluntary daemon retirement.
The raw-SQL writer permit remains handle-scoped even in autocommit. This read acquires no connection and changes no admission policy.
Sourcepub fn origin(&self) -> TxOrigin
pub fn origin(&self) -> TxOrigin
This pool’s ADR-091 backend-scoped attribution origin (ADR-091,
backend-scoped WAL-pin attribution design note): Database(_) for a
file-backed pool, Memory for an in-memory pool. Every
tx_registry::register_scoped call site threaded in this crate
passes this value as the span’s origin.
Sourcepub fn canonical_path(&self) -> Option<&Path>
pub fn canonical_path(&self) -> Option<&Path>
The canonical path this pool’s origin() identity was minted from,
None for an in-memory pool. DbIdentity has no path accessor by
design; sidecar derivation and other filesystem consumers use this —
the same canonical value the identity was minted from — instead of
re-deriving a path from the raw configured one.
Sourcepub fn opened_file_identity(&self) -> Option<(u64, u64)>
pub fn opened_file_identity(&self) -> Option<(u64, u64)>
Unix file identity retained for callers using the original tuple API.
Sourcepub fn opened_file_identity_record(&self) -> Option<DatabaseFileIdentity>
pub fn opened_file_identity_record(&self) -> Option<DatabaseFileIdentity>
Physical file identity pinned to SQLite’s opened main file. Construction compares it with the path on both sides of the open before admission.
Sourcepub fn database_owner_identity(
&self,
) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError>
pub fn database_owner_identity( &self, ) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError>
Ownership evidence captured through the database SQLite opened. This does not select the topology’s main backend or establish a root binding. Legacy read-only and low-space opens without a stored UUID must reopen after installation; this accessor never installs or re-mints an identity.
Sourcepub fn verify_database_owner(
&self,
expected: &DatabaseOwnerIdentity,
) -> Result<(), DatabaseOwnerIdentityError>
pub fn verify_database_owner( &self, expected: &DatabaseOwnerIdentity, ) -> Result<(), DatabaseOwnerIdentityError>
Require both this opened database’s UUID and physical file to match.
Sourcepub fn write_queue_active(&self) -> bool
pub fn write_queue_active(&self) -> bool
Whether the write queue is effectively enabled for this pool: the
resolved write_queue_enabled flag AND file-backed.
ConnectionPool::new resolves the “no preference” (None) preference
to a concrete Some(..) once path is known, so every reader of
config.write_queue_enabled sees a resolved value; the debug_assert
pins that invariant and a None that slipped past would read as
disabled. Bypassing ConnectionPool::new to construct a pool is a
construction-path bug. Use this instead of repeating
config().write_queue_enabled.unwrap_or(false) && config().path.is_some()
at every routing/violation site.
Sourcepub fn writer_task_join_was_stored(&self) -> bool
pub fn writer_task_join_was_stored(&self) -> bool
Whether a writer-task JoinHandle has been stored at least once.
Unlike Self::take_writer_task_join, this remains true after the
one-shot handle slot is emptied, distinguishing a task that never
spawned from a handle another caller already consumed.
Sourcepub fn writer_task_handle(
&self,
) -> Result<Option<WriterTaskHandle>, StorageError>
pub fn writer_task_handle( &self, ) -> Result<Option<WriterTaskHandle>, StorageError>
Return the pool-wide ADR-067 Component A writer task, spawning it
lazily on first access if PoolConfig::write_queue_enabled is set.
Exactly one writer task exists per ConnectionPool (per DB file); see
crates/khive-db/docs/api/pool.md#connectionpoolwriter_task_handle–single-writer-task-rationale
for why a per-store writer task would defeat the single-writer
guarantee.
Returns Ok(None) if the flag is off, or if the writer task failed to
spawn for a reason other than a missing runtime (for example, an
in-memory pool has no standalone-connection support) — callers fall
back to the legacy pool-mutex write path in either case. A spawn
failure is logged once here (at first access), not once per store.
Returns Err(StorageError::WriterTaskNoRuntime) instead of panicking
when write_queue_enabled is set but this is the first access and no
Tokio runtime is available on the calling thread (checked via
tokio::runtime::Handle::try_current) — spawning the writer task
requires tokio::spawn, which panics outside a runtime. Callers that
already treat a missing writer task as best-effort (construction-time
degrade to the legacy path, matching slice 1’s documented policy) can
collapse this into None with .ok().flatten(); callers that need to
fail loud on a genuine misconfiguration (write queue requested but no
runtime to run it on) can propagate the Err directly.
Sourcepub fn writer_task_for_runtime_write(
&self,
operation: RuntimeWriteOperation,
) -> Result<Option<WriterTaskHandle>, StorageError>
pub fn writer_task_for_runtime_write( &self, operation: RuntimeWriteOperation, ) -> Result<Option<WriterTaskHandle>, StorageError>
Resolve a runtime-owned transaction through the same strict/compatibility
policy as store writes. None permits the caller’s direct transaction and
records its compatibility fallback when the file-backed queue is enabled.
A strict refusal returns before any direct-writer acquisition or telemetry.
Sourcepub fn take_writer_task_join(&self) -> Option<JoinHandle<()>>
pub fn take_writer_task_join(&self) -> Option<JoinHandle<()>>
Take the writer task’s JoinHandle, if a writer task was spawned and the handle has not already been taken.
Intended for short-lived batch callers that drop every
WriterTaskHandle clone (closing the queue) and then need to await
the task’s exit before treating the database file as settled: the
task’s connection close fires SQLite’s close-time WAL checkpoint, so
until the task exits the file bytes can still move after the caller’s
last write returned.
One-shot: None means either the write queue never spawned
(disabled, or spawn degraded) or another caller already took the
handle — in both cases there is nothing further to await here.
Exactly one subsystem may own the drain: the single caller that
receives Some(_) is the sole owner of the task-exit await (and of
the close-time WAL checkpoint that settles the database file); every
later caller receives None and must not arrange its own await.
Sourcepub fn open_standalone_checkpoint(
&self,
) -> Result<StandaloneCheckpoint<'_>, SqliteError>
pub fn open_standalone_checkpoint( &self, ) -> Result<StandaloneCheckpoint<'_>, SqliteError>
Retain a dedicated recovery connection without granting ordinary SQL. This bypasses logical-write admission so a checkpoint can reclaim space.
Sourcepub fn checkpoint_owner_present(&self) -> bool
pub fn checkpoint_owner_present(&self) -> bool
Whether a checkpoint owner is claiming or has claimed this pool. A host without that owner’s join must conservatively refuse teardown.
Sourcepub fn timeout_sink_close_handle(&self) -> Option<TimeoutSinkCloseHandle>
pub fn timeout_sink_close_handle(&self) -> Option<TimeoutSinkCloseHandle>
Retain this pool’s diagnostic sink completion witness before Drop. Explicit close waits until all pools and writer tasks sharing the sink have released their ownership; ordinary Drop never stops the sink.
Sourcepub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError>
pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError>
Claim routine WAL-checkpoint ownership for this pool.
Called by the scheduled checkpoint task at startup — the one caller
that actually replaces SQLite’s per-commit autocheckpoint with
dedicated PASSIVE checkpointing (ADR-091 Amendment 10). The claim
makes every subsequently opened writer-capable connection set
PRAGMA wal_autocheckpoint = 0, and re-applies that pragma on the
already-open pooled writer under the writer mutex. A writer task
spawned before the claim keeps its own long-lived connection;
Self::propagate_checkpoint_claim_to_writer_task reaches that one.
Without a claim, writer-capable connections keep the bounded
FALLBACK_WAL_AUTOCHECKPOINT_PAGES threshold, so a writable pool
in a process that never runs the checkpoint task (embedded runtimes,
one-shot CLI executions) retains SQLite’s own WAL reclamation instead
of growing its WAL without bound.
Read-only pools record the claim but have no writer-capable connections to reconfigure. Writable pools publish the claim only after the pooled writer is configured successfully; a failed attempt keeps the bounded fallback active and remains retryable.
Sourcepub async fn propagate_checkpoint_claim_to_writer_task(
&self,
) -> Result<(), StorageError>
pub async fn propagate_checkpoint_claim_to_writer_task( &self, ) -> Result<(), StorageError>
Flip an already-running writer task’s long-lived connection to the claimed-owner setting.
Connections opened after Self::claim_checkpoint_ownership inherit
wal_autocheckpoint = 0 at open; only a writer task spawned before
the claim still holds a connection on the bounded fallback. Returns
Ok(()) without side effects when the pool’s write queue is
disabled.
Source§impl ConnectionPool
impl ConnectionPool
Sourcepub fn standalone_autocommit<R>(
&self,
operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
) -> Result<R, SqliteError>
pub fn standalone_autocommit<R>( &self, operation: impl FnOnce(&Connection) -> Result<R, SqliteError>, ) -> Result<R, SqliteError>
Run one standalone autocommit operation or complete SQL script.
The connection and volume lease remain owned by this call. Capacity
is checked immediately before the callback. A script may contain
complete transactions, but returning with a transaction still open
rolls it back and reports an error. Use Self::standalone_transaction
when this API should own BEGIN IMMEDIATE and COMMIT instead.
The callback cannot return a connection borrow:
use khive_db::ConnectionPool;
fn escape(pool: &ConnectionPool) {
let _connection = pool.standalone_autocommit(|conn| Ok(conn));
}Sourcepub fn standalone_transaction<R>(
&self,
operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
) -> Result<R, SqliteError>
pub fn standalone_transaction<R>( &self, operation: impl FnOnce(&Connection) -> Result<R, SqliteError>, ) -> Result<R, SqliteError>
Run a standalone BEGIN IMMEDIATE transaction under the volume lease.
Capacity is sampled after BEGIN succeeds and before the callback. This call owns COMMIT/ROLLBACK; the callback must not settle the outer transaction itself. A panic drops the owned connection before the lease can be released.
Sourcepub fn run_migrations(&self) -> Result<u32, SqliteError>
pub fn run_migrations(&self) -> Result<u32, SqliteError>
Run core migrations while preserving owner-before-lease-before-writer order for callers that hold a pool but not a backend wrapper.
Trait Implementations§
Source§impl Drop for ConnectionPool
impl Drop for ConnectionPool
Source§fn drop(&mut self)
fn drop(&mut self)
Close every read-only reader before the fields below it drop in
declaration order (writer first, readers well before
writer_task). A read-only connection cannot take the EXCLUSIVE lock
SQLite needs to checkpoint on close, so if a reader were left to close
last, WAL mode would leave -wal/-shm behind. Draining readers
here, before that field-order drop runs, makes the writable writer
connection close after every reader instead of before it.