Skip to main content

uqa_storage_sqlite/
connection.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Pooled `SQLite` connections with explicit session and transaction affinity.
8//!
9//! A [`ManagedConnection`] is a logical session. Clones share that session so
10//! catalog, document, inverted-index, and vector stores participate in the
11//! same explicit transaction. [`ManagedConnection::new_session`] creates an
12//! isolated session over the same physical connection pool. Outside explicit
13//! transactions operations check out independent connections, allowing WAL
14//! readers to make real concurrent progress.
15
16use std::path::{Path, PathBuf};
17use std::sync::{Arc, OnceLock};
18
19use parking_lot::{Mutex, RwLock};
20use rusqlite::{Connection, OpenFlags};
21use uqa_storage::{mvcc::VersionedKeyValueStore, KeyValueStore, StorageEncryptionKey};
22
23use crate::compressed_vfs::{self, SQLiteCompressedContainerAnchor, SQLiteCompressionOptions};
24
25mod identity;
26mod logical;
27mod native;
28mod native_restore;
29pub(crate) mod ownership;
30mod pool;
31mod restore;
32use pool::ConnectionPool;
33pub(crate) use pool::PooledConnection;
34mod notifications;
35mod serializable;
36mod snapshot;
37use snapshot::PhysicalConnection;
38pub(crate) use snapshot::SnapshotIdentity;
39
40#[derive(Debug, thiserror::Error)]
41pub enum SQLiteError {
42    #[error(transparent)]
43    Memory(#[from] uqa_core::memory::MemoryError),
44    #[error(transparent)]
45    Cancelled(#[from] uqa_core::QueryCancelled),
46    #[error("text analysis failed: {0}")]
47    Analysis(#[from] uqa_analysis::AnalysisError),
48    #[error("sqlite error: {0}")]
49    SQLite(#[from] rusqlite::Error),
50    #[error("encryption key must not be empty")]
51    EmptyEncryptionKey,
52    #[error("database requires an encryption key")]
53    EncryptionKeyRequired,
54    #[error("database is not encrypted but an encryption key was provided")]
55    NotEncrypted,
56    #[error("auxiliary database requires DELETE journaling, found {0}")]
57    AuxiliaryJournalMode(String),
58    #[error("compressed sqlite container error: {0}")]
59    CompressedContainer(String),
60    #[error("io error: {0}")]
61    Io(#[from] std::io::Error),
62    #[error("catalog migration {version} failed: {source}")]
63    Migration {
64        version: u32,
65        #[source]
66        source: rusqlite::Error,
67    },
68    #[error("invalid persisted catalog schema version `{0}`")]
69    InvalidSchemaVersion(String),
70    #[error("catalog schema version {found} is newer than this engine supports ({supported})")]
71    UnsupportedSchemaVersion { found: u32, supported: u32 },
72    #[error("corrupt document blob for `{table}` doc {doc_id} field `{field}`: {reason}")]
73    CorruptDocumentBlob {
74        table: String,
75        doc_id: u64,
76        field: String,
77        reason: String,
78    },
79    #[error("payload serialization failed: {0}")]
80    Serde(#[from] serde_json::Error),
81    #[error("storage backend error: {0}")]
82    StorageBackend(String),
83    #[error(transparent)]
84    StorageSource(Box<uqa_storage::StorageBackendError>),
85    #[error("transaction already active for this sqlite session")]
86    TransactionAlreadyActive,
87    #[error("no active transaction for this sqlite session")]
88    NoActiveTransaction,
89    #[error("sqlite transaction was aborted by an earlier storage error: {0}")]
90    TransactionAborted(String),
91    #[error("sqlite session cleanup failed: {0}")]
92    SessionCleanupFailed(String),
93    #[error("sqlite connection-pool checkout lost its connection")]
94    MissingCheckedOutConnection,
95    #[error("versioned storage requires its logical session; use with_physical only for explicit physical maintenance")]
96    LogicalSessionRequired,
97    #[error("database restoration requires all existing owners to close")]
98    DatabaseRestoreBusy,
99    #[error("database restoration is incomplete; resume the original source/target request")]
100    DatabaseRestoreIncomplete,
101    #[error("the SQLite session already has a different retention limit")]
102    SessionOptionsMismatch,
103    #[error("the SQLite session is bound to a different record mapping")]
104    SessionMappingMismatch,
105}
106
107pub type Result<T> = std::result::Result<T, SQLiteError>;
108
109const MIN_POOL_CONNECTIONS: usize = 4;
110const MAX_POOL_CONNECTIONS: usize = 32;
111
112#[derive(Clone)]
113enum ConnectionSpec {
114    File {
115        path: PathBuf,
116        key: Option<StorageEncryptionKey>,
117    },
118    Auxiliary {
119        path: PathBuf,
120        key: Option<StorageEncryptionKey>,
121    },
122    Compressed {
123        path: PathBuf,
124        compression: SQLiteCompressionOptions,
125        key: Option<StorageEncryptionKey>,
126    },
127    Memory,
128}
129
130impl ConnectionSpec {
131    fn open(&self, initialize_database: bool) -> Result<Connection> {
132        match self {
133            Self::File { path, key } | Self::Auxiliary { path, key } => {
134                let conn = Connection::open(path)?;
135                if let Some(key) = key {
136                    ManagedConnection::apply_encryption_key(&conn, key.expose_secret())?;
137                }
138                if matches!(self, Self::Auxiliary { .. }) {
139                    // Registry writers already serialize their transactions.
140                    // Retain the original journal mode instead of racing to
141                    // promote a new registry to WAL during concurrent opens.
142                    let mode: String =
143                        conn.pragma_query_value(None, "journal_mode", |row| row.get(0))?;
144                    if mode != "delete" {
145                        return Err(SQLiteError::AuxiliaryJournalMode(mode));
146                    }
147                    ManagedConnection::configure_rollback_connection(&conn)?;
148                } else {
149                    if initialize_database {
150                        ManagedConnection::enable_wal(&conn)?;
151                    }
152                    ManagedConnection::configure_wal_connection(&conn)?;
153                }
154                Ok(conn)
155            }
156            Self::Compressed {
157                path, compression, ..
158            } => {
159                let conn = Connection::open_with_flags_and_vfs(
160                    path,
161                    OpenFlags::default(),
162                    compressed_vfs::VFS_NAME,
163                )?;
164                if initialize_database {
165                    conn.pragma_update(None, "page_size", compression.page_size)?;
166                    ManagedConnection::enable_compressed_journal(&conn)?;
167                }
168                ManagedConnection::configure_rollback_connection(&conn)?;
169                Ok(conn)
170            }
171            Self::Memory => {
172                let conn = Connection::open_in_memory()?;
173                if initialize_database {
174                    ManagedConnection::enable_wal(&conn)?;
175                }
176                ManagedConnection::configure_wal_connection(&conn)?;
177                Ok(conn)
178            }
179        }
180    }
181}
182
183struct SessionState {
184    write_cancellation: uqa_core::CancellationToken,
185    affinity: uqa_storage::StorageSessionAffinity,
186    /// Read guards cover ordinary operations. Transaction lifecycle calls take
187    /// the write guard, making BEGIN/COMMIT/ROLLBACK linearizable with respect
188    /// to every operation issued through the same logical session.
189    gate: RwLock<()>,
190    transaction: Mutex<Option<PooledConnection>>,
191    transaction_failure: Mutex<Option<String>>,
192    cleanup_failure: Mutex<Option<String>>,
193    logical: OnceLock<Arc<logical::BoundRecordSession>>,
194    native_restore: Mutex<Option<native_restore::NativeRestore>>,
195    snapshot_branch: Mutex<Arc<()>>,
196}
197
198impl SessionState {
199    fn new() -> Self {
200        Self::with_cancellation(uqa_core::CancellationToken::new())
201    }
202
203    fn with_cancellation(write_cancellation: uqa_core::CancellationToken) -> Self {
204        Self {
205            write_cancellation,
206            affinity: uqa_storage::StorageSessionAffinity::new(),
207            gate: RwLock::new(()),
208            transaction: Mutex::new(None),
209            transaction_failure: Mutex::new(None),
210            cleanup_failure: Mutex::new(None),
211            logical: OnceLock::new(),
212            native_restore: Mutex::new(None),
213            snapshot_branch: Mutex::new(Arc::new(())),
214        }
215    }
216}
217
218impl Drop for SessionState {
219    fn drop(&mut self) {
220        // `PooledConnection::drop` performs the rollback and discards the
221        // physical connection when rollback itself fails. Taking the pinned
222        // handle here therefore cannot return a broken connection to the pool.
223        self.native_restore.get_mut().take();
224        self.transaction.get_mut().take();
225    }
226}
227
228/// Logical `SQLite` session backed by a bounded physical connection pool.
229/// Cloning preserves session/transaction affinity; call [`Self::new_session`]
230/// for an independently isolated transaction context.
231#[derive(Clone)]
232pub struct ManagedConnection {
233    pool: Arc<ConnectionPool>,
234    session: Arc<SessionState>,
235    record_access: bool,
236}
237
238impl ManagedConnection {
239    fn surface_cleanup_failure(&self) -> Result<()> {
240        if let Some(error) = self.session.cleanup_failure.lock().take() {
241            return Err(SQLiteError::SessionCleanupFailed(error));
242        }
243        Ok(())
244    }
245
246    pub fn open(path: &Path) -> Result<Self> {
247        if path == Path::new(":memory:") {
248            return Self::open_in_memory();
249        }
250        Self::open_with_optional_key(path, None)
251    }
252
253    /// Retain the database credential for encrypted auxiliary storage, including
254    /// compressed containers whose main-file encryption lives in the VFS.
255    #[must_use]
256    pub fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey> {
257        match &self.pool.spec {
258            ConnectionSpec::File { key, .. }
259            | ConnectionSpec::Auxiliary { key, .. }
260            | ConnectionSpec::Compressed { key, .. } => key.clone(),
261            ConnectionSpec::Memory => None,
262        }
263    }
264
265    /// Lease an independent physical connection without joining this logical
266    /// session's transaction. The pool retains encryption and connection policy.
267    pub fn lease_connection(&self) -> Result<crate::SQLiteConnectionLease> {
268        self.pool.checkout().map(crate::SQLiteConnectionLease)
269    }
270
271    /// Open database-owned auxiliary storage with its inherited credential and
272    /// original DELETE journaling. Concurrent first opens never change journal
273    /// modes. An incompatible existing mode is rejected without rewriting it.
274    pub fn open_auxiliary(path: &Path, key: Option<StorageEncryptionKey>) -> Result<Self> {
275        if path == Path::new(":memory:") || path.as_os_str().is_empty() {
276            return Err(SQLiteError::StorageBackend(
277                "auxiliary storage requires a database file".into(),
278            ));
279        }
280        Self::from_spec(
281            ConnectionSpec::Auxiliary {
282                path: path.to_path_buf(),
283                key,
284            },
285            default_pool_connections(),
286        )
287    }
288
289    pub fn open_encrypted(path: &Path, key: &str) -> Result<Self> {
290        Self::open_with_optional_key(path, Some(key))
291    }
292
293    pub fn open_compressed(path: &Path, compression: SQLiteCompressionOptions) -> Result<Self> {
294        Self::open_compressed_with_optional_key(path, compression, None, None)
295    }
296
297    pub fn open_compressed_encrypted(
298        path: &Path,
299        key: &str,
300        compression: SQLiteCompressionOptions,
301    ) -> Result<Self> {
302        if key.is_empty() {
303            return Err(SQLiteError::EmptyEncryptionKey);
304        }
305        Self::open_compressed_with_optional_key(path, compression, Some(key), None)
306    }
307
308    /// Open an encrypted compressed database while enforcing an exact trusted
309    /// external state anchor in the VFS main-file open path.
310    pub fn open_compressed_encrypted_with_anchor(
311        path: &Path,
312        key: &str,
313        compression: SQLiteCompressionOptions,
314        trusted_anchor: SQLiteCompressedContainerAnchor,
315    ) -> Result<Self> {
316        if key.is_empty() {
317            return Err(SQLiteError::EmptyEncryptionKey);
318        }
319        Self::open_compressed_with_optional_key(path, compression, Some(key), Some(trusted_anchor))
320    }
321
322    fn open_with_optional_key(path: &Path, key: Option<&str>) -> Result<Self> {
323        let spec = ConnectionSpec::File {
324            path: path.to_path_buf(),
325            key: key.map(StorageEncryptionKey::new),
326        };
327        Self::from_spec(spec, default_pool_connections())
328    }
329
330    fn open_compressed_with_optional_key(
331        path: &Path,
332        compression: SQLiteCompressionOptions,
333        key: Option<&str>,
334        trusted_anchor: Option<SQLiteCompressedContainerAnchor>,
335    ) -> Result<Self> {
336        let compression = compression
337            .validate()
338            .map_err(SQLiteError::CompressedContainer)?;
339        let owner = ownership::open(
340            path,
341            &uqa_storage::read_control::StorageReadControl::with_limit(
342                uqa_storage::mvcc::VersionedSessionOptions::default().retained_bytes,
343            ),
344        )?;
345        match trusted_anchor {
346            Some(anchor) => compressed_vfs::register_database_with_anchor(
347                path,
348                compression,
349                key.ok_or(SQLiteError::EncryptionKeyRequired)?,
350                anchor,
351            ),
352            None => compressed_vfs::register_database(path, compression, key),
353        }
354        .map_err(SQLiteError::CompressedContainer)?;
355        let spec = ConnectionSpec::Compressed {
356            path: path.to_path_buf(),
357            compression,
358            key: key.map(StorageEncryptionKey::new),
359        };
360        Self::from_spec_owned(spec, default_pool_connections(), Some(owner))
361    }
362
363    pub fn open_in_memory() -> Result<Self> {
364        // Independent `:memory:` connections do not share a database. Keep a
365        // one-connection pool for this special target; file-backed databases
366        // use the real multi-connection pool.
367        Self::from_spec(ConnectionSpec::Memory, 1)
368    }
369
370    fn from_spec(spec: ConnectionSpec, max_connections: usize) -> Result<Self> {
371        let owner = match &spec {
372            ConnectionSpec::File { path, .. }
373                if path.as_os_str().is_empty() || path == Path::new(":memory:") =>
374            {
375                None
376            }
377            ConnectionSpec::File { path, .. }
378            | ConnectionSpec::Auxiliary { path, .. }
379            | ConnectionSpec::Compressed { path, .. } => Some(ownership::open(
380                path,
381                &uqa_storage::read_control::StorageReadControl::with_limit(
382                    uqa_storage::mvcc::VersionedSessionOptions::default().retained_bytes,
383                ),
384            )?),
385            ConnectionSpec::Memory => None,
386        };
387        Self::from_spec_owned(spec, max_connections, owner)
388    }
389
390    fn from_spec_owned(
391        spec: ConnectionSpec,
392        max_connections: usize,
393        owner: Option<Arc<ownership::DatabaseOwner>>,
394    ) -> Result<Self> {
395        let initial = spec.open(true)?;
396        crate::mvcc::restore::reject_pending(&initial)?;
397        Ok(Self {
398            pool: ConnectionPool::new(spec, initial, max_connections, owner),
399            session: Arc::new(SessionState::new()),
400            record_access: false,
401        })
402    }
403
404    pub(crate) fn database_owner(&self) -> Option<Arc<ownership::DatabaseOwner>> {
405        self.pool.owner.clone()
406    }
407
408    fn apply_encryption_key(conn: &Connection, key: &str) -> Result<()> {
409        if key.is_empty() {
410            return Err(SQLiteError::EmptyEncryptionKey);
411        }
412        conn.pragma_update(None, "key", key)?;
413        Ok(())
414    }
415
416    fn enable_wal(conn: &Connection) -> Result<()> {
417        conn.pragma_update(None, "journal_mode", "WAL")?;
418        Ok(())
419    }
420
421    fn configure_wal_connection(conn: &Connection) -> Result<()> {
422        // Legacy physical operations retain a bounded busy wait. Versioned writes supply cancellable admission under a scoped timeout.
423        conn.busy_timeout(std::time::Duration::from_secs(5))?;
424        // Synchronous=NORMAL is the recommended pairing with WAL: safe
425        // against power loss, faster than FULL.
426        conn.pragma_update(None, "synchronous", "NORMAL")?;
427        // Foreign keys are off by default; turn on so per-table cleanup
428        // can use ON DELETE CASCADE later.
429        conn.pragma_update(None, "foreign_keys", "ON")?;
430        Ok(())
431    }
432
433    fn enable_compressed_journal(conn: &Connection) -> Result<()> {
434        // The compressed VFS implements the byte-addressed database file.
435        // Rollback journals stay raw because they are short-lived commit
436        // machinery; compressing them only adds autocommit write amplification.
437        // WAL requires shared-memory VFS methods, so compressed databases use
438        // SQLite's rollback journal and keep temp storage in memory.
439        conn.pragma_update(None, "journal_mode", "DELETE")?;
440        Ok(())
441    }
442
443    fn configure_rollback_connection(conn: &Connection) -> Result<()> {
444        conn.busy_timeout(std::time::Duration::from_secs(5))?;
445        conn.pragma_update(None, "synchronous", "FULL")?;
446        conn.pragma_update(None, "temp_store", "MEMORY")?;
447        conn.pragma_update(None, "foreign_keys", "ON")?;
448        Ok(())
449    }
450
451    /// Identity shared by handles using this session's native or logical transaction context.
452    pub fn transaction_affinity(&self) -> uqa_storage::StorageSessionAffinity {
453        let _gate = self.session.gate.read();
454        self.session.logical.get().map_or_else(
455            || self.session.affinity.clone(),
456            |logical| logical.session_affinity(),
457        )
458    }
459
460    /// Whether this session has an active native or logical record transaction.
461    #[must_use]
462    pub fn in_transaction(&self) -> bool {
463        let _gate = self.session.gate.read();
464        if let Some(logical) = self.session.logical.get() {
465            return logical.in_transaction();
466        }
467        self.session.transaction.lock().is_some()
468    }
469
470    /// Whether this session has staged writes, including private logical records. Callers use this to enforce read-only execution boundaries before COMMIT.
471    pub fn transaction_has_written(&self) -> Result<bool> {
472        let _gate = self.session.gate.read();
473        if let Some(logical) = self.session.logical.get() {
474            return logical.transaction_has_written().map_err(Into::into);
475        }
476        let transaction = self.session.transaction.lock();
477        let transaction = transaction
478            .as_ref()
479            .ok_or(SQLiteError::NoActiveTransaction)?;
480        Ok(matches!(
481            transaction.connection()?.transaction_state(Some("main"))?,
482            rusqlite::TransactionState::Write
483        ))
484    }
485
486    /// Whether this session's independent [`Self::data_version`] monitor can
487    /// read without contending with the currently pinned transaction.
488    ///
489    /// 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.
490    pub fn data_version_monitor_is_nonblocking(&self) -> Result<bool> {
491        let _gate = self.session.gate.read();
492        if self.session.logical.get().is_some() {
493            return Ok(true);
494        }
495        if !matches!(
496            &self.pool.spec,
497            ConnectionSpec::Compressed { .. } | ConnectionSpec::Auxiliary { .. }
498        ) {
499            return Ok(true);
500        }
501        Ok(self.session.transaction.lock().is_none())
502    }
503
504    /// 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.
505    #[must_use]
506    pub fn supports_concurrent_pinned_read_and_write(&self) -> bool {
507        let _gate = self.session.gate.read();
508        self.session.logical.get().is_some()
509            || !matches!(
510                &self.pool.spec,
511                ConnectionSpec::Compressed { .. } | ConnectionSpec::Auxiliary { .. }
512            )
513    }
514
515    /// Database change counter observed on one stable connection shared by
516    /// every logical session over this pool. The value changes when another
517    /// `SQLite` connection commits. In-memory databases have no independent
518    /// connections and therefore return `None`.
519    pub fn data_version(&self) -> Result<Option<u64>> {
520        let _gate = self.session.gate.read();
521        if let Some(logical) = self.session.logical.get() {
522            return logical.change_version().map_err(Into::into);
523        }
524        if matches!(&self.pool.spec, ConnectionSpec::Memory) {
525            return Ok(None);
526        }
527        let mut monitor = self.pool.data_version_monitor.lock();
528        if monitor.is_none() {
529            *monitor = Some(self.pool.spec.open(false)?);
530        }
531        let monitor = monitor.as_ref().ok_or_else(|| {
532            SQLiteError::StorageBackend(
533                "data-version monitor was not initialized after opening it".into(),
534            )
535        })?;
536        let version: i64 = monitor.pragma_query_value(None, "data_version", |row| row.get(0))?;
537        let version = u64::try_from(version).map_err(|_| {
538            SQLiteError::StorageBackend(format!(
539                "SQLite returned a negative PRAGMA data_version: {version}"
540            ))
541        })?;
542        Ok(Some(version))
543    }
544
545    /// Establish the database snapshot for the active transaction without
546    /// depending on the caller's first user query. `BEGIN DEFERRED` alone does
547    /// not start a read transaction, so a writer could otherwise commit after
548    /// the engine checks its cache generations but before the first catalog
549    /// read. Reading `sqlite_schema` is database-wide and keeps the operation
550    /// independent of any application table.
551    pub fn pin_transaction_snapshot(&self) -> Result<()> {
552        self.surface_cleanup_failure()?;
553        let _gate = self.session.gate.read();
554        if let Some(logical) = self.session.logical.get() {
555            return if logical.in_transaction() {
556                Ok(())
557            } else {
558                Err(SQLiteError::NoActiveTransaction)
559            };
560        }
561        self.with_native(|connection| {
562            if connection.is_autocommit() {
563                return Err(SQLiteError::NoActiveTransaction);
564            }
565            let _: i64 =
566                connection.query_row("SELECT COUNT(*) FROM sqlite_schema", [], |row| row.get(0))?;
567            Ok(())
568        })
569    }
570
571    /// Run a closure using this session. Outside a transaction the closure
572    /// checks out a pooled connection; inside a transaction every clone is
573    /// routed to the session's pinned connection.
574    pub fn with<R>(&self, f: impl FnOnce(&Connection) -> Result<R>) -> Result<R> {
575        self.surface_cleanup_failure()?;
576        let _gate = self.session.gate.read();
577        if self.session.logical.get().is_some() {
578            return Err(SQLiteError::LogicalSessionRequired);
579        }
580        self.with_native(f)
581    }
582
583    /// The caller holds the session gate and has ruled out logical record access.
584    fn with_native<R>(&self, f: impl FnOnce(&Connection) -> Result<R>) -> Result<R> {
585        let transaction = self.session.transaction.lock();
586        if let Some(connection) = transaction.as_ref() {
587            if let Some(error) = self.session.transaction_failure.lock().as_ref() {
588                return Err(SQLiteError::TransactionAborted(error.clone()));
589            }
590            self.check_native_access(connection.connection()?)?;
591            let result = f(connection.connection()?);
592            if let Err(error) = &result {
593                let mut failure = self.session.transaction_failure.lock();
594                if failure.is_none() {
595                    *failure = Some(error.to_string());
596                }
597            }
598            return result;
599        }
600        drop(transaction);
601        let connection = self.pool.checkout()?;
602        self.check_native_access(connection.connection()?)?;
603        f(connection.connection()?)
604    }
605
606    pub fn with_mut<R>(&self, f: impl FnOnce(&mut Connection) -> Result<R>) -> Result<R> {
607        self.with_physical_mut(|physical| f(&mut physical.connection))
608    }
609
610    fn with_physical_mut<R>(
611        &self,
612        f: impl FnOnce(&mut PhysicalConnection) -> Result<R>,
613    ) -> Result<R> {
614        self.surface_cleanup_failure()?;
615        let _gate = self.session.gate.read();
616        if self.session.logical.get().is_some() {
617            return Err(SQLiteError::LogicalSessionRequired);
618        }
619        let mut transaction = self.session.transaction.lock();
620        if let Some(connection) = transaction.as_mut() {
621            if let Some(error) = self.session.transaction_failure.lock().as_ref() {
622                return Err(SQLiteError::TransactionAborted(error.clone()));
623            }
624            self.check_native_access(connection.connection()?)?;
625            let result = f(connection.physical_mut()?);
626            if let Err(error) = &result {
627                let mut failure = self.session.transaction_failure.lock();
628                if failure.is_none() {
629                    *failure = Some(error.to_string());
630                }
631            }
632            return result;
633        }
634        drop(transaction);
635        let mut connection = self.pool.checkout()?;
636        self.check_native_access(connection.connection()?)?;
637        f(connection.physical_mut()?)
638    }
639
640    /// 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.
641    pub fn vacuum(&self) -> Result<()> {
642        self.surface_cleanup_failure()?;
643        let _gate = self.session.gate.write();
644        if self.session.transaction.lock().is_some()
645            || self
646                .session
647                .logical
648                .get()
649                .is_some_and(|logical| logical.in_transaction())
650        {
651            return Err(SQLiteError::TransactionAlreadyActive);
652        }
653        if let Some(logical) = self.session.logical.get() {
654            logical.reclaim_versions()?;
655        }
656        let connection = self.pool.checkout()?;
657        connection.connection()?.execute_batch("VACUUM")?;
658        Ok(())
659    }
660
661    /// Open an explicit (non-deferred) transaction. Subsequent
662    /// auto-commit hosts (catalog writes, FTS index updates, ...) all
663    /// flow through the same connection so the transaction enclosing
664    /// them is honoured. Use [`Self::commit_transaction`] /
665    /// [`Self::rollback_transaction`] / [`Self::savepoint`] etc. for
666    /// the lifecycle.
667    pub fn begin_transaction(&self) -> Result<()> {
668        self.begin_transaction_with("BEGIN IMMEDIATE")
669    }
670
671    /// Open a deferred transaction. Read-only SQL statements use this mode
672    /// so WAL readers do not take the single writer reservation; if a scalar
673    /// routine performs a write, `SQLite` upgrades the same transaction and
674    /// still preserves the statement's atomic boundary.
675    pub fn begin_deferred_transaction(&self) -> Result<()> {
676        self.begin_transaction_with("BEGIN DEFERRED")
677    }
678
679    fn begin_transaction_with(&self, statement: &str) -> Result<()> {
680        self.surface_cleanup_failure()?;
681        let _gate = self.session.gate.write();
682        if let Some(logical) = self.session.logical.get() {
683            if logical.in_transaction() {
684                return Err(SQLiteError::TransactionAlreadyActive);
685            }
686            return if statement == "BEGIN DEFERRED" {
687                logical.begin_upgradeable_transaction()
688            } else {
689                logical.begin_transaction()
690            }
691            .map_err(Into::into);
692        }
693        let mut transaction = self.session.transaction.lock();
694        if transaction.is_some() {
695            return Err(SQLiteError::TransactionAlreadyActive);
696        }
697        let connection = self.pool.checkout()?;
698        self.check_native_access(connection.connection()?)?;
699        connection.connection()?.execute_batch(statement)?;
700        self.session.transaction_failure.lock().take();
701        *transaction = Some(connection);
702        Ok(())
703    }
704
705    pub fn commit_transaction(&self) -> Result<()> {
706        self.surface_cleanup_failure()?;
707        self.finish_transaction("COMMIT")
708    }
709
710    pub fn rollback_transaction(&self) -> Result<()> {
711        self.surface_cleanup_failure()?;
712        self.finish_transaction("ROLLBACK")
713    }
714
715    /// Drop-only transaction cleanup. A rollback error is recorded on the
716    /// logical session and is returned by its next operation instead of being
717    /// mistaken for a successful rollback.
718    pub(crate) fn rollback_transaction_on_drop(&self) {
719        if let Err(error) = self.finish_transaction("ROLLBACK") {
720            let mut failure = self.session.cleanup_failure.lock();
721            if failure.is_none() {
722                *failure = Some(error.to_string());
723            }
724        }
725    }
726
727    fn finish_transaction(&self, statement: &str) -> Result<()> {
728        let _gate = self.session.gate.write();
729        if let Some(logical) = self.session.logical.get() {
730            if !logical.in_transaction() {
731                return Err(SQLiteError::NoActiveTransaction);
732            }
733            return if statement == "COMMIT" {
734                logical.commit_transaction()
735            } else {
736                logical.rollback_transaction()
737            }
738            .map_err(Into::into);
739        }
740        let mut transaction = self.session.transaction.lock();
741        let connection = transaction
742            .as_ref()
743            .ok_or(SQLiteError::NoActiveTransaction)?;
744        *self.session.snapshot_branch.lock() = Arc::new(());
745        if statement == "COMMIT" {
746            // Materialize the failure before entering the branch. Holding the
747            // mutex guard created by an `if let` scrutinee until the end of
748            // the branch would deadlock when cleanup takes the same lock.
749            let transaction_failure = self.session.transaction_failure.lock().clone();
750            if let Some(error) = transaction_failure {
751                if let Err(rollback_error) = connection.connection()?.execute_batch("ROLLBACK") {
752                    self.session.native_restore.lock().take();
753                    transaction.take();
754                    self.session.transaction_failure.lock().take();
755                    return Err(SQLiteError::SQLite(rollback_error));
756                }
757                self.session.native_restore.lock().take();
758                transaction.take();
759                self.session.transaction_failure.lock().take();
760                return Err(SQLiteError::TransactionAborted(error));
761            }
762        }
763        let native = if statement == "COMMIT" && self.session.native_restore.lock().is_some() {
764            match self.prepare_initial_native_binding(connection.connection()?) {
765                Ok(native) => Some(native),
766                Err(error) => {
767                    *self.session.transaction_failure.lock() = Some(error.to_string());
768                    return Err(error);
769                }
770            }
771        } else {
772            None
773        };
774        if let Err(error) = connection.connection()?.execute_batch(statement) {
775            self.session.native_restore.lock().take();
776            transaction.take();
777            self.session.transaction_failure.lock().take();
778            return Err(SQLiteError::SQLite(error));
779        }
780        self.session.native_restore.lock().take();
781        transaction.take();
782        self.session.transaction_failure.lock().take();
783        if let Some(native) = native {
784            self.install_initial_native_binding(native);
785        }
786        Ok(())
787    }
788
789    fn with_transaction<R>(
790        &self,
791        logical: impl FnOnce(&VersionedKeyValueStore) -> uqa_storage::StorageBackendResult<R>,
792        native: impl FnOnce(&Connection) -> Result<R>,
793    ) -> Result<R> {
794        self.surface_cleanup_failure()?;
795        let _gate = self.session.gate.read();
796        if let Some(store) = self.session.logical.get() {
797            if !store.in_transaction() {
798                return Err(SQLiteError::NoActiveTransaction);
799            }
800            return logical(store).map_err(Into::into);
801        }
802        let transaction = self.session.transaction.lock();
803        let connection = transaction
804            .as_ref()
805            .ok_or(SQLiteError::NoActiveTransaction)?;
806        self.check_native_access(connection.connection()?)?;
807        native(connection.connection()?)
808    }
809
810    pub fn savepoint(&self, name: &str) -> Result<()> {
811        self.with_transaction(
812            |logical| logical.savepoint(name),
813            |connection| {
814                let stmt = format!("SAVEPOINT \"{}\"", name.replace('"', "\"\""));
815                connection.execute_batch(&stmt)?;
816                Ok(())
817            },
818        )
819    }
820
821    pub fn release_savepoint(&self, name: &str) -> Result<()> {
822        self.with_transaction(
823            |logical| logical.release_savepoint(name),
824            |connection| {
825                let stmt = format!("RELEASE SAVEPOINT \"{}\"", name.replace('"', "\"\""));
826                connection.execute_batch(&stmt)?;
827                Ok(())
828            },
829        )
830    }
831
832    pub fn rollback_to_savepoint(&self, name: &str) -> Result<()> {
833        self.with_transaction(
834            |logical| logical.rollback_to_savepoint(name),
835            |connection| {
836                let stmt = format!("ROLLBACK TO SAVEPOINT \"{}\"", name.replace('"', "\"\""));
837                connection.execute_batch(&stmt)?;
838                self.session.transaction_failure.lock().take();
839                *self.session.snapshot_branch.lock() = Arc::new(());
840                Ok(())
841            },
842        )
843    }
844}
845
846fn default_pool_connections() -> usize {
847    std::thread::available_parallelism()
848        .map_or(MIN_POOL_CONNECTIONS, |parallelism| parallelism.get() * 2)
849        .clamp(MIN_POOL_CONNECTIONS, MAX_POOL_CONNECTIONS)
850}
851
852#[cfg(test)]
853mod tests;
854
855impl From<uqa_storage::mvcc::VersionError> for SQLiteError {
856    fn from(error: uqa_storage::mvcc::VersionError) -> Self {
857        Self::from(error.into_storage_error())
858    }
859}
860
861impl From<SQLiteError> for uqa_storage::StorageBackendError {
862    fn from(source: SQLiteError) -> Self {
863        match source {
864            SQLiteError::Memory(error) => Self::Memory(error),
865            SQLiteError::Cancelled(error) => Self::Cancelled(error),
866            SQLiteError::StorageSource(error) => *error,
867            source => Self::backend("SQLite", source),
868        }
869    }
870}
871
872impl From<SQLiteError> for uqa_storage::TransactionError {
873    fn from(source: SQLiteError) -> Self {
874        Self::Storage(source.into())
875    }
876}
877
878impl From<uqa_storage::StorageBackendError> for SQLiteError {
879    fn from(error: uqa_storage::StorageBackendError) -> Self {
880        use uqa_storage::StorageBackendError;
881        match error {
882            StorageBackendError::Memory(error) => Self::Memory(error),
883            StorageBackendError::Cancelled(error) => Self::Cancelled(error),
884            StorageBackendError::Analysis(error) => Self::Analysis(error),
885            StorageBackendError::Serde(error) => Self::Serde(error),
886            StorageBackendError::Backend { backend, source } => match source.downcast::<Self>() {
887                Ok(error) => *error,
888                Err(source) => {
889                    Self::StorageSource(Box::new(StorageBackendError::Backend { backend, source }))
890                }
891            },
892            StorageBackendError::Other(message) => Self::StorageBackend(message),
893        }
894    }
895}