Struct SqlitePool 

pub struct SqlitePool { /* private fields */ }

Thread-safe SQLite connection wrapper.

Backed by an r2d2 pool of rusqlite::Connections with WAL mode enabled, so concurrent reads can proceed in parallel (writes are still serialized at the SQLite level). Replaces the previous Arc<Mutex<Connection>> shape that funnelled every operation through a single mutex (Wave F, Issue 68).

When an Encryptor is set, content columns are transparently encrypted on write and decrypted on read by the store layers.

Implementations

impl SqlitePool

pub fn latest_schema_version() -> i64

The highest schema version this build knows how to apply — the version a freshly migrated database lands on. Used by the open-time reconciliation gate to detect a future (downgrade) schema and by doctor to report binary-vs-disk skew.

pub fn schema_version(&self) -> Result<i64, SqliteError>

Get the current schema version.

impl SqlitePool

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

Open a new SQLite database at the given path.

• Creates the file if it doesn’t exist
• Enables WAL mode for concurrent reads
• Enables foreign keys
• Reconciles the on-disk schema version against this build (refuses a future schema; snapshots before a forward migration)
• Runs all schema migrations

pub fn open_with( path: &Path, allow_downgrade: bool, ) -> Result<Self, SqliteError>

Like SqlitePool::open, but allow_downgrade suppresses the SqliteError::SchemaTooNew guard so an older binary can be forced onto a newer on-disk schema. The forward-only migration runner still won’t alter the schema downward — this only un-gates the open so a recovery/export path can read what it can.

pub fn open_memory() -> Result<Self, SqliteError>

Open an in-memory database (for testing).

Pool size is forced to 1 — multiple Connection::open_in_memory handles each get a fresh DB, which would break any test that writes from one checkout and reads from another. Single connection preserves the legacy single-connection semantics.

pub fn with_conn<F, T>(&self, f: F) -> Result<T, SqliteError>

where F: FnOnce(&Connection) -> Result<T, SqliteError>,

Execute a closure with a connection borrowed from the pool.

The connection returns to the pool when the closure exits. Multiple concurrent readers can hold distinct connections at the same time; writes still serialize at the SQLite level (single-writer is fundamental to SQLite, WAL or not).

pub fn open_connections(&self) -> u32

Number of connections the r2d2 pool currently holds (idle + checked out), capped by the configured max_size. Backs the open-connections resource gauge; a value pinned at the max for a sustained period is a sign of connection-pressure or a leak.

pub fn with_encryptor(self, enc: Encryptor) -> Self

Attach an encryptor to this pool (builder pattern).

Once set, encrypt_content / decrypt_content are active on all store layers that use this pool.

pub fn is_encrypted(&self) -> bool

Returns true if an encryptor is active.

pub fn encrypt_content(&self, plaintext: &str) -> String

Encrypt a string if encryption is enabled, otherwise return as-is.

pub fn decrypt_content(&self, maybe_ciphertext: &str) -> String

Decrypt a string if encryption is enabled.

Falls back to returning the input unchanged if decryption fails (e.g. legacy plaintext rows written before encryption was enabled).

pub fn try_decrypt_content(&self, maybe_ciphertext: &str) -> Option<String>

Try to decrypt a string, returning None if decryption fails.

Unlike decrypt_content, this does NOT fall back to returning raw ciphertext. Use this at read boundaries to filter out rows that were encrypted with a different key or are corrupted.

pub fn wal_checkpoint(&self) -> Result<(), SqliteError>

Flush the WAL file into the main database file.

Should be called on graceful shutdown to ensure all committed writes are fully persisted and the WAL file is clean. Uses TRUNCATE mode which also resets the WAL to zero size.

pub fn insert_scheduled_intent( &self, description: &str, cron: Option<&str>, namespace: &str, metadata: Option<&str>, ) -> Result<String, SqliteError>

Persist a scheduled intent and return its generated ID.

pub fn list_scheduled_intents( &self, namespace: Option<&str>, ) -> Result<Vec<ScheduledIntent>, SqliteError>

List scheduled intents, optionally filtered by namespace.

pub fn update_scheduled_intent_status( &self, id: &str, status: &str, ) -> Result<bool, SqliteError>

Update a scheduled intent status. Returns true when a row was updated.

pub fn cancel_scheduled_intent(&self, id: &str) -> Result<bool, SqliteError>

Cancel a scheduled intent (set status to “cancelled”).

pub fn due_scheduled_intents(&self) -> Result<Vec<ScheduledIntent>, SqliteError>

Return all scheduled intents with status "scheduled" (i.e. pending execution).

pub fn insert_notification( &self, content: &str, priority: i32, triggered_by: &str, channel: Option<&str>, ) -> Result<String, SqliteError>

Insert a notification into the outbox for later delivery.

pub fn pending_notifications( &self, limit: usize, ) -> Result<Vec<Notification>, SqliteError>

Fetch all pending (undelivered) notifications, ordered by priority then age.

pub fn mark_notification_delivered(&self, id: &str) -> Result<bool, SqliteError>

Mark a notification as delivered (sets delivered_at to now).

pub fn mark_notifications_delivered( &self, ids: &[String], ) -> Result<usize, SqliteError>

Mark multiple notifications as delivered in a single UPDATE. Returns the count of notifications actually marked delivered.

pub fn prune_notifications( &self, max_age_days: u32, ) -> Result<usize, SqliteError>

Prune old delivered notifications and stale undelivered ones.

pub fn export_all_facts(&self) -> Result<Vec<ExportedFact>, SqliteError>

Export all semantic facts ordered by ID.

pub fn export_all_episodes(&self) -> Result<Vec<ExportedEpisode>, SqliteError>

Export all episodes with session info, ordered by timestamp.

pub fn import_facts( &self, facts: &[ExportedFact], ) -> Result<(usize, Vec<usize>), SqliteError>

Import facts (ON CONFLICT DO NOTHING). Returns (imported_count, new_indices).

pub fn import_episodes( &self, episodes: &[ExportedEpisode], ) -> Result<usize, SqliteError>

Import episodes (ON CONFLICT DO NOTHING). Returns count of newly imported episodes.

pub fn table_stats(&self) -> Result<Vec<(String, i64)>, SqliteError>

Get table row counts for status display.

Trait Implementations

impl Clone for SqlitePool

fn clone(&self) -> SqlitePool

Returns a duplicate of the value.

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

Performs copy-assignment from source.