Skip to main content

uqa_storage_sqlite/
backend.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Session factories and physical stores for the `SQLite` backend.
8
9use crate::{
10    Catalog, ManagedConnection, SQLiteBTreeIndexStore, SQLiteDocumentStore, SQLiteHNSWIndex,
11    SQLiteIVFIndex, SQLiteInvertedIndex, SQLiteVectorIndex,
12};
13use std::{collections::BTreeMap, sync::Arc};
14use uqa_analysis::Analyzer;
15use uqa_core::{DocId, Value};
16use uqa_storage::{
17    CatalogFacade, DocumentStore, InvertedIndex, PersistentStorageBackend,
18    PersistentStorageIdentity, PersistentStorageProvider, PersistentStorageSession,
19    StorageBackendResult, StorageSavepointId, VectorIndex, VectorIndexOpenMode, VectorIndexSpec,
20};
21
22#[derive(Clone)]
23pub struct SQLiteStorageBackend {
24    conn: ManagedConnection,
25    native_initial_restore: bool,
26}
27
28impl SQLiteStorageBackend {
29    pub fn new(conn: ManagedConnection) -> Self {
30        Self {
31            conn,
32            native_initial_restore: false,
33        }
34    }
35
36    pub fn connection(&self) -> ManagedConnection {
37        self.conn.clone()
38    }
39
40    /// Create a backend whose stores use an independent transaction session
41    /// over the same physical `SQLite` pool.
42    #[must_use]
43    pub fn new_session(&self) -> Self {
44        Self::new(self.conn.new_session())
45    }
46}
47
48/// Database-level owner that creates isolated `SQLite` engine sessions.
49#[derive(Clone)]
50pub struct SQLiteStorageProvider {
51    connection: ManagedConnection,
52}
53
54impl SQLiteStorageProvider {
55    pub fn new(connection: ManagedConnection) -> Self {
56        Self { connection }
57    }
58
59    fn native_session(
60        &self,
61        cancellation: &uqa_core::CancellationToken,
62    ) -> StorageBackendResult<ManagedConnection> {
63        if !self.connection.is_native_record_session() {
64            self.connection
65                .bind_native_records(uqa_storage::mvcc::VersionedSessionOptions::default())?;
66        }
67        Ok(self.connection.new_session_with_cancellation(cancellation))
68    }
69}
70
71impl PersistentStorageProvider for SQLiteStorageProvider {
72    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
73        self.connection.auxiliary_encryption_key()
74    }
75
76    fn open_initial_session(&self) -> StorageBackendResult<PersistentStorageSession> {
77        let connection = self.connection.new_session();
78        let catalog: Arc<dyn CatalogFacade> =
79            Arc::new(Catalog::for_initial_restore(connection.clone()));
80        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(SQLiteStorageBackend {
81            conn: connection,
82            native_initial_restore: true,
83        });
84        Ok(PersistentStorageSession::new(catalog, backend))
85    }
86
87    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
88        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
89    }
90
91    fn open_session_with_cancellation(
92        &self,
93        cancellation: &uqa_core::CancellationToken,
94    ) -> StorageBackendResult<PersistentStorageSession> {
95        cancellation.check()?;
96        let connection = self.native_session(cancellation)?;
97        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
98        let backend: Arc<dyn PersistentStorageBackend> =
99            Arc::new(SQLiteStorageBackend::new(connection));
100        Ok(PersistentStorageSession::new(catalog, backend))
101    }
102
103    fn storage_identity(&self) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
104        self.connection.storage_identity()
105    }
106}
107
108impl uqa_storage::mvcc::IdentifierAllocator for SQLiteStorageBackend {
109    fn identifier_watermark(&self, namespace: &[u8]) -> StorageBackendResult<Option<u64>> {
110        self.conn
111            .native_identifier_watermark(namespace)
112            .map_err(Into::into)
113    }
114
115    fn allocate_identifiers(
116        &self,
117        namespace: &[u8],
118        request: uqa_storage::mvcc::IdentifierRequest,
119    ) -> StorageBackendResult<uqa_storage::mvcc::IdentifierAllocation> {
120        self.conn
121            .allocate_native_identifiers(namespace, request)
122            .map_err(Into::into)
123    }
124
125    fn observe_identifier(
126        &self,
127        namespace: &[u8],
128        value: u64,
129    ) -> StorageBackendResult<uqa_storage::mvcc::ObservedIdentifier> {
130        self.conn
131            .observe_native_identifier(namespace, value)
132            .map_err(Into::into)
133    }
134}
135
136impl PersistentStorageBackend for SQLiteStorageBackend {
137    fn require_sequence_value_durability(&self) -> StorageBackendResult<()> {
138        self.conn
139            .require_sequence_value_durability()
140            .map_err(Into::into)
141    }
142
143    fn open_sequence_value_session(
144        &self,
145        cancellation: &uqa_core::CancellationToken,
146    ) -> StorageBackendResult<PersistentStorageSession> {
147        let connection = self.conn.new_sequence_value_session(cancellation)?;
148        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
149        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
150        Ok(PersistentStorageSession::new(catalog, backend))
151    }
152
153    fn retention_control(&self) -> Option<uqa_storage::read_control::StorageReadControl> {
154        self.conn.retention_control()
155    }
156
157    fn notification_publications(
158        &self,
159    ) -> Option<&dyn uqa_storage::notifications::NotificationPublicationStore> {
160        Some(&self.conn)
161    }
162
163    fn serializable_session(&self) -> Option<&dyn uqa_storage::mvcc::SerializableSession> {
164        self.conn
165            .is_native_record_session()
166            .then_some(&self.conn as &dyn uqa_storage::mvcc::SerializableSession)
167    }
168
169    fn open_retained_read_session(
170        &self,
171        cancellation: &uqa_core::CancellationToken,
172    ) -> StorageBackendResult<PersistentStorageSession> {
173        let connection = self.conn.new_retained_read_session(cancellation)?;
174        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
175        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
176        Ok(PersistentStorageSession::new(catalog, backend))
177    }
178
179    fn capture_committed_read_boundary(
180        &self,
181    ) -> StorageBackendResult<Arc<uqa_storage::mvcc::CommittedReadBoundary>> {
182        self.conn.capture_committed_read_boundary()
183    }
184
185    fn open_read_session_with_private_changes(
186        &self,
187        boundary: &uqa_storage::mvcc::CommittedReadBoundary,
188        cancellation: &uqa_core::CancellationToken,
189    ) -> StorageBackendResult<PersistentStorageSession> {
190        let connection = self
191            .conn
192            .new_read_session_with_private_changes(boundary, cancellation)?;
193        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
194        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
195        Ok(PersistentStorageSession::new(catalog, backend))
196    }
197
198    fn write_cancellation(&self) -> Option<uqa_core::CancellationToken> {
199        Some(self.conn.write_cancellation())
200    }
201
202    fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
203        self.conn.transaction_model()
204    }
205
206    fn identifier_allocator(&self) -> Option<&dyn uqa_storage::mvcc::IdentifierAllocator> {
207        self.conn.is_native_record_session().then_some(self)
208    }
209
210    fn transaction_affinity(&self) -> Option<uqa_storage::StorageSessionAffinity> {
211        Some(self.conn.transaction_affinity())
212    }
213
214    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
215        self.conn.auxiliary_encryption_key()
216    }
217
218    fn storage_identity(&self) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
219        self.conn.storage_identity()
220    }
221
222    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
223        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
224    }
225
226    fn open_session_with_cancellation(
227        &self,
228        cancellation: &uqa_core::CancellationToken,
229    ) -> StorageBackendResult<PersistentStorageSession> {
230        cancellation.check()?;
231        let connection = self.conn.new_session_with_cancellation(cancellation);
232        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
233        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
234        Ok(PersistentStorageSession::new(catalog, backend))
235    }
236
237    fn open_controlled_session(
238        &self,
239        control: &uqa_storage::read_control::StorageReadControl,
240    ) -> StorageBackendResult<PersistentStorageSession> {
241        let connection = self.conn.new_controlled_session(control)?;
242        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
243        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
244        Ok(PersistentStorageSession::new(catalog, backend))
245    }
246
247    fn supports_concurrent_pinned_read_and_write(&self) -> bool {
248        self.conn.supports_concurrent_pinned_read_and_write()
249    }
250
251    fn document_store(&self, table: &str) -> Box<dyn DocumentStore> {
252        Box::new(SQLiteDocumentStore::new(self.conn.clone(), table))
253    }
254
255    fn inverted_index(&self, table: &str, analyzer: Analyzer) -> Box<dyn InvertedIndex> {
256        Box::new(SQLiteInvertedIndex::new(self.conn.clone(), table, analyzer))
257    }
258
259    fn vector_index(
260        &self,
261        table: &str,
262        field: &str,
263        dimensions: u32,
264        spec: VectorIndexSpec,
265        mode: VectorIndexOpenMode,
266    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
267        let index: Box<dyn VectorIndex> = match spec {
268            VectorIndexSpec::DiskANN(_) => {
269                return Err(uqa_storage::StorageBackendError::Other(
270                    "DiskANN requires an actual catalog binding".into(),
271                ))
272            }
273            VectorIndexSpec::BruteForce => Box::new(SQLiteVectorIndex::new(
274                self.conn.clone(),
275                table,
276                field,
277                dimensions,
278            )),
279            VectorIndexSpec::IVF(params) => {
280                params.validate()?;
281                match mode {
282                    VectorIndexOpenMode::Create => Box::new(SQLiteIVFIndex::with_params(
283                        self.conn.clone(),
284                        table,
285                        field,
286                        dimensions,
287                        params.nlist,
288                        params.nprobe,
289                        params.train_threshold,
290                    )),
291                    VectorIndexOpenMode::Restore => Box::new(SQLiteIVFIndex::open_existing(
292                        self.conn.clone(),
293                        table,
294                        field,
295                        dimensions,
296                        params.nlist,
297                        params.nprobe,
298                        params.train_threshold,
299                    )),
300                }
301            }
302            VectorIndexSpec::HNSW(params) => {
303                params.validate()?;
304                match mode {
305                    VectorIndexOpenMode::Create => Box::new(SQLiteHNSWIndex::with_params(
306                        self.conn.clone(),
307                        table,
308                        field,
309                        dimensions,
310                        params,
311                    )),
312                    VectorIndexOpenMode::Restore => {
313                        let index = SQLiteHNSWIndex::open_existing(
314                            self.conn.clone(),
315                            table,
316                            field,
317                            dimensions,
318                            params,
319                        );
320                        index.validate_existing()?;
321                        Box::new(index)
322                    }
323                }
324            }
325        };
326        Ok(index)
327    }
328
329    fn diskann_index(
330        &self,
331        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
332        options: uqa_storage::diskann_index::DiskANNIndexOptions,
333        temporary: &uqa_storage::diskann_index::build::DiskANNTemporaryBudget,
334        mode: VectorIndexOpenMode,
335    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
336        let canonical = crate::vector_index::SQLiteDiskANNCanonical::new(
337            self.conn.clone(),
338            binding.table,
339            binding.field,
340            binding.dimensions,
341        )?;
342        if mode == VectorIndexOpenMode::Create {
343            canonical.create_index(
344                binding.index,
345                &*binding.resolver,
346                options,
347                temporary,
348                binding.control,
349            )?;
350        }
351        let handle = canonical.bind(
352            binding.index.clone(),
353            binding.resolver,
354            options.read,
355            binding.control,
356        )?;
357        Ok(Box::new(
358            uqa_storage::diskann_index::PersistentDiskANNIndex::new(handle, options, temporary)?,
359        ))
360    }
361
362    fn diskann_journal_pruner(
363        &self,
364        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
365        max_record_bytes: usize,
366    ) -> StorageBackendResult<Box<dyn uqa_storage::diskann_index::changes::DiskANNJournalPruner>>
367    {
368        crate::vector_index::SQLiteDiskANNCanonical::new(
369            self.conn.clone(),
370            binding.table,
371            binding.field,
372            binding.dimensions,
373        )?
374        .journal_pruner(
375            binding.index,
376            binding.resolver,
377            max_record_bytes,
378            binding.control,
379        )
380    }
381
382    fn diskann_maintenance_source(
383        &self,
384        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
385        max_record_bytes: usize,
386    ) -> StorageBackendResult<
387        Box<dyn uqa_storage::diskann_index::maintenance::DiskANNMaintenanceSource>,
388    > {
389        crate::vector_index::SQLiteDiskANNCanonical::new(
390            self.conn.clone(),
391            binding.table,
392            binding.field,
393            binding.dimensions,
394        )?
395        .maintenance_source(
396            binding.index,
397            binding.resolver,
398            max_record_bytes,
399            binding.control,
400        )
401    }
402
403    fn retire_diskann_index(
404        &self,
405        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
406    ) -> StorageBackendResult<()> {
407        crate::vector_index::SQLiteDiskANNCanonical::new(
408            self.conn.clone(),
409            binding.table,
410            binding.field,
411            binding.dimensions,
412        )?
413        .retire_index(binding.index, &*binding.resolver, binding.control)
414    }
415
416    fn drop_vector_index_metadata(&self, table: &str, field: &str) -> StorageBackendResult<()> {
417        SQLiteIVFIndex::drop_metadata(&self.conn, table, field)?;
418        SQLiteHNSWIndex::drop_metadata(&self.conn, table, field)?;
419        Ok(())
420    }
421
422    fn persists_btree_indexes(&self) -> bool {
423        true
424    }
425
426    fn load_btree_index(
427        &self,
428        table: &str,
429        field: &uqa_storage::ValueIndexKey,
430    ) -> StorageBackendResult<Option<Vec<(DocId, Value)>>> {
431        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).load(table, field)?)
432    }
433
434    fn btree_index_fields(
435        &self,
436        table: &str,
437    ) -> StorageBackendResult<Vec<uqa_storage::ValueIndexKey>> {
438        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).fields(table)?)
439    }
440
441    fn probe_btree_index_equal(
442        &self,
443        table: &str,
444        field: &uqa_storage::ValueIndexKey,
445        value: &Value,
446    ) -> StorageBackendResult<Option<Vec<DocId>>> {
447        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).probe_equal(table, field, value)?)
448    }
449
450    fn visit_btree_index_entries(
451        &self,
452        table: &str,
453        field: &uqa_storage::ValueIndexKey,
454        visit: &mut dyn FnMut(DocId, Value) -> StorageBackendResult<()>,
455    ) -> StorageBackendResult<bool> {
456        SQLiteBTreeIndexStore::new(self.conn.clone()).visit_entries(table, field, visit)
457    }
458
459    fn visit_btree_index_equal(
460        &self,
461        table: &str,
462        field: &uqa_storage::ValueIndexKey,
463        value: &Value,
464        visit: &mut dyn FnMut(DocId) -> bool,
465    ) -> StorageBackendResult<bool> {
466        Ok(
467            SQLiteBTreeIndexStore::new(self.conn.clone())
468                .visit_equal(table, field, value, visit)?,
469        )
470    }
471
472    fn read_btree_index_entry(
473        &self,
474        table: &str,
475        field: &uqa_storage::ValueIndexKey,
476        doc_id: DocId,
477    ) -> StorageBackendResult<uqa_storage::ValueIndexEntry> {
478        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).read_entry(table, field, doc_id)?)
479    }
480
481    fn btree_index_repairs(
482        &self,
483    ) -> StorageBackendResult<Vec<(String, uqa_storage::ValueIndexKey)>> {
484        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).repairs()?)
485    }
486
487    fn clear_btree_index_repair(
488        &self,
489        table: &str,
490        field: &uqa_storage::ValueIndexKey,
491    ) -> StorageBackendResult<()> {
492        SQLiteBTreeIndexStore::new(self.conn.clone()).clear_repair(table, field)?;
493        Ok(())
494    }
495
496    fn replace_btree_index(
497        &self,
498        table: &str,
499        field: &uqa_storage::ValueIndexKey,
500        values: &[(DocId, Value)],
501    ) -> StorageBackendResult<()> {
502        SQLiteBTreeIndexStore::new(self.conn.clone()).replace(table, field, values)?;
503        Ok(())
504    }
505
506    fn repair_btree_index(
507        &self,
508        table: &str,
509        field: &uqa_storage::ValueIndexKey,
510        _complete: &[(DocId, Value)],
511        stale_doc_ids: &[DocId],
512        missing: &[(DocId, Value)],
513    ) -> StorageBackendResult<()> {
514        SQLiteBTreeIndexStore::new(self.conn.clone()).repair(
515            table,
516            field,
517            stale_doc_ids,
518            missing,
519        )?;
520        Ok(())
521    }
522
523    fn replace_btree_indexes(
524        &self,
525        table: &str,
526        indexes: &[(&uqa_storage::ValueIndexKey, &[(DocId, Value)])],
527    ) -> StorageBackendResult<()> {
528        SQLiteBTreeIndexStore::new(self.conn.clone()).replace_many(table, indexes)?;
529        Ok(())
530    }
531
532    fn apply_btree_index_write(
533        &self,
534        table: &str,
535        doc_id: DocId,
536        values: Option<&BTreeMap<uqa_storage::ValueIndexKey, Value>>,
537    ) -> StorageBackendResult<()> {
538        SQLiteBTreeIndexStore::new(self.conn.clone()).apply_write(table, doc_id, values)?;
539        Ok(())
540    }
541
542    fn apply_unused_btree_index_write(
543        &self,
544        table: &str,
545        doc_id: DocId,
546        values: &BTreeMap<uqa_storage::ValueIndexKey, Value>,
547        namespace: uqa_storage::document_store::identifiers::DocumentIdNamespace,
548    ) -> StorageBackendResult<()> {
549        SQLiteBTreeIndexStore::new(self.conn.clone())
550            .apply_unused_write(table, doc_id, values, namespace)?;
551        Ok(())
552    }
553
554    fn drop_btree_index(
555        &self,
556        table: &str,
557        field: &uqa_storage::ValueIndexKey,
558    ) -> StorageBackendResult<()> {
559        SQLiteBTreeIndexStore::new(self.conn.clone()).drop_index(table, field)?;
560        Ok(())
561    }
562
563    fn clear_btree_indexes(&self, table: &str) -> StorageBackendResult<()> {
564        SQLiteBTreeIndexStore::new(self.conn.clone()).clear_table(table)?;
565        Ok(())
566    }
567
568    fn vacuum(&self) -> StorageBackendResult<()> {
569        self.conn.vacuum()?;
570        Ok(())
571    }
572
573    fn reclaim_obsolete(&self) -> StorageBackendResult<()> {
574        self.conn.reclaim_obsolete().map_err(Into::into)
575    }
576
577    fn begin_transaction(&self) -> StorageBackendResult<()> {
578        self.conn.begin_transaction()?;
579        Ok(())
580    }
581
582    fn begin_read_transaction(&self) -> StorageBackendResult<()> {
583        self.conn.begin_deferred_transaction()?;
584        Ok(())
585    }
586
587    fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()> {
588        if self.native_initial_restore && !self.conn.is_native_record_session() {
589            self.conn.begin_native_initial_restore()?;
590        } else {
591            self.conn.begin_deferred_transaction()?;
592        }
593        Ok(())
594    }
595
596    fn refresh_transaction_snapshot(
597        &self,
598        cancellation: &uqa_core::CancellationToken,
599    ) -> StorageBackendResult<()> {
600        self.conn.refresh_transaction_snapshot(cancellation)?;
601        Ok(())
602    }
603
604    fn in_transaction(&self) -> bool {
605        self.conn.in_transaction()
606    }
607
608    fn transaction_has_written(&self) -> StorageBackendResult<bool> {
609        Ok(self.conn.transaction_has_written()?)
610    }
611
612    fn change_version(&self) -> StorageBackendResult<Option<u64>> {
613        Ok(self.conn.data_version()?)
614    }
615
616    fn read_view_revision(
617        &self,
618    ) -> StorageBackendResult<Option<uqa_storage::key_value::KeyValueReadRevision>> {
619        Ok(self.conn.read_view_revision()?)
620    }
621
622    fn committed_data_revision(
623        &self,
624    ) -> StorageBackendResult<Option<uqa_storage::CommittedDataRevision>> {
625        Ok(self.conn.committed_data_revision())
626    }
627
628    fn commit_monitor_version(&self) -> StorageBackendResult<Option<u64>> {
629        Ok(self.conn.commit_monitor_version()?)
630    }
631
632    fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool> {
633        Ok(self.conn.data_version_monitor_is_nonblocking()?)
634    }
635
636    fn pin_transaction_snapshot(&self) -> StorageBackendResult<()> {
637        self.conn.pin_transaction_snapshot()?;
638        Ok(())
639    }
640
641    fn prepare_transaction_commit(&self) -> StorageBackendResult<()> {
642        self.conn.prepare_transaction_commit()?;
643        Ok(())
644    }
645
646    fn commit_transaction(&self) -> StorageBackendResult<()> {
647        self.conn.commit_transaction()?;
648        Ok(())
649    }
650
651    fn rollback_transaction(&self) -> StorageBackendResult<()> {
652        self.conn.rollback_transaction()?;
653        Ok(())
654    }
655
656    fn savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
657        self.conn.savepoint(&id.backend_name())?;
658        Ok(())
659    }
660
661    fn release_savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
662        self.conn.release_savepoint(&id.backend_name())?;
663        Ok(())
664    }
665
666    fn rollback_to_savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
667        self.conn.rollback_to_savepoint(&id.backend_name())?;
668        Ok(())
669    }
670}
671
672#[cfg(test)]
673mod tests {
674    use std::collections::BTreeMap;
675
676    use uqa_analysis::analyzer::standard_analyzer;
677    use uqa_core::Value;
678    use uqa_storage::StorageBackendError;
679
680    use super::*;
681    use crate::{Catalog, SQLiteError};
682
683    #[test]
684    fn session_factories_preserve_a_bound_native_sessions_retention_options() {
685        let connection = ManagedConnection::open_in_memory().unwrap();
686        connection
687            .bind_native_records(uqa_storage::mvcc::VersionedSessionOptions {
688                retained_bytes: 8 << 20,
689            })
690            .unwrap();
691        let provider = SQLiteStorageProvider::new(connection);
692        let initial = provider.open_initial_session().unwrap();
693        let sibling = provider.open_session().unwrap();
694        initial.validate_transaction_affinity().unwrap();
695        sibling.validate_transaction_affinity().unwrap();
696        assert!(initial.backend.transaction_model().is_versioned());
697        assert_eq!(
698            initial.backend.transaction_model(),
699            sibling.backend.transaction_model()
700        );
701        assert_ne!(
702            initial.backend.transaction_affinity(),
703            sibling.backend.transaction_affinity()
704        );
705    }
706
707    #[test]
708    fn session_factory_reads_current_catalog_while_a_sibling_holds_a_writer_reservation() {
709        let directory = tempfile::tempdir().unwrap();
710        let connection = ManagedConnection::open_compressed(
711            &directory.path().join("session-writer-reservation.db"),
712            crate::SQLiteCompressionOptions::default(),
713        )
714        .unwrap();
715        let provider = SQLiteStorageProvider::new(connection);
716        let writer = provider.open_session().unwrap();
717        writer.backend.begin_transaction().unwrap();
718        writer
719            .catalog
720            .set_metadata("private-write", "uncommitted")
721            .unwrap();
722
723        let reader = provider.open_session().unwrap();
724        assert_eq!(reader.catalog.get_metadata("private-write").unwrap(), None);
725        writer.backend.commit_transaction().unwrap();
726        assert_eq!(
727            reader
728                .catalog
729                .get_metadata("private-write")
730                .unwrap()
731                .as_deref(),
732            Some("uncommitted")
733        );
734    }
735
736    #[test]
737    fn sqlite_backend_builds_document_index_and_vector_stores() {
738        let conn = ManagedConnection::open_in_memory().unwrap();
739        let _catalog = Catalog::open(conn.clone()).unwrap();
740        let backend = SQLiteStorageBackend::new(conn);
741
742        let mut doc = BTreeMap::new();
743        doc.insert("title".to_string(), Value::Str("rust storage".into()));
744        let mut docs = backend.document_store("articles");
745        docs.put(1, doc).unwrap();
746        assert_eq!(
747            docs.get_field(1, "title").unwrap(),
748            Some(Value::Str("rust storage".into()))
749        );
750
751        let mut inv = backend.inverted_index("articles", standard_analyzer("english"));
752        inv.add_document(
753            1,
754            BTreeMap::from([("title".to_string(), "rust storage".to_string())]),
755        )
756        .unwrap();
757        assert_eq!(inv.doc_freq("title", "rust").unwrap(), 1);
758
759        let mut vectors = backend
760            .vector_index(
761                "articles",
762                "embedding",
763                2,
764                VectorIndexSpec::IVF(uqa_storage::IVFIndexParams {
765                    nlist: 2,
766                    nprobe: 1,
767                    train_threshold: 2,
768                }),
769                VectorIndexOpenMode::Create,
770            )
771            .unwrap();
772        vectors.add(1, vec![1.0, 0.0]).unwrap();
773        let hits = vectors.search_knn(&[1.0, 0.0], 1).unwrap();
774        assert_eq!(hits.entries().len(), 1);
775        assert_eq!(hits.entries()[0].doc_id, 1);
776    }
777
778    #[test]
779    fn sqlite_backend_transaction_rolls_back_cross_store_writes() {
780        let conn = ManagedConnection::open_in_memory().unwrap();
781        let _catalog = Catalog::open(conn.clone()).unwrap();
782        let backend = SQLiteStorageBackend::new(conn);
783        let mut docs = backend.document_store("articles");
784        let mut inv = backend.inverted_index("articles", standard_analyzer("english"));
785
786        backend.begin_transaction().unwrap();
787        docs.put(
788            1,
789            BTreeMap::from([("title".to_string(), Value::Str("rollback".into()))]),
790        )
791        .unwrap();
792        inv.add_document(
793            1,
794            BTreeMap::from([("title".to_string(), "rollback".to_string())]),
795        )
796        .unwrap();
797        backend.rollback_transaction().unwrap();
798
799        assert_eq!(docs.len().unwrap(), 0);
800        assert_eq!(inv.doc_freq("title", "rollback").unwrap(), 0);
801    }
802
803    #[test]
804    fn sqlite_sessions_isolate_and_atomically_commit_cross_store_writes() {
805        let dir = tempfile::tempdir().unwrap();
806        let path = dir.path().join("cross-store-isolation.sqlite3");
807        let conn = ManagedConnection::open(&path).unwrap();
808        let catalog = Catalog::open(conn.clone()).unwrap();
809        let writer = SQLiteStorageBackend::new(conn.clone());
810        let observer_conn = conn.new_session();
811        let observer_catalog = Catalog::open(observer_conn.clone()).unwrap();
812        let observer = SQLiteStorageBackend::new(observer_conn);
813
814        let mut writer_docs = writer.document_store("articles");
815        let mut writer_inv = writer.inverted_index("articles", standard_analyzer("english"));
816        let mut writer_vectors = writer
817            .vector_index(
818                "articles",
819                "embedding",
820                2,
821                VectorIndexSpec::BruteForce,
822                VectorIndexOpenMode::Create,
823            )
824            .unwrap();
825        let observer_docs = observer.document_store("articles");
826        let observer_inv = observer.inverted_index("articles", standard_analyzer("english"));
827        let observer_vectors = observer
828            .vector_index(
829                "articles",
830                "embedding",
831                2,
832                VectorIndexSpec::BruteForce,
833                VectorIndexOpenMode::Restore,
834            )
835            .unwrap();
836
837        writer.begin_transaction().unwrap();
838        writer_docs
839            .put(
840                1,
841                BTreeMap::from([("title".to_string(), Value::Str("atomic rust".into()))]),
842            )
843            .unwrap();
844        writer_inv
845            .add_document(
846                1,
847                BTreeMap::from([("title".to_string(), "atomic rust".to_string())]),
848            )
849            .unwrap();
850        writer_vectors.add(1, vec![1.0, 0.0]).unwrap();
851        catalog
852            .save_scoring_params("transactional", r#"{"alpha":1.0}"#)
853            .unwrap();
854
855        assert_eq!(writer_docs.len().unwrap(), 1);
856        assert_eq!(writer_inv.doc_freq("title", "rust").unwrap(), 1);
857        assert_eq!(writer_vectors.count().unwrap(), 1);
858        assert!(catalog
859            .load_scoring_params("transactional")
860            .unwrap()
861            .is_some());
862
863        assert_eq!(observer_docs.len().unwrap(), 0);
864        assert_eq!(observer_inv.doc_freq("title", "rust").unwrap(), 0);
865        assert_eq!(observer_vectors.count().unwrap(), 0);
866        assert!(observer_catalog
867            .load_scoring_params("transactional")
868            .unwrap()
869            .is_none());
870
871        writer.commit_transaction().unwrap();
872        assert_eq!(observer_docs.len().unwrap(), 1);
873        assert_eq!(observer_inv.doc_freq("title", "rust").unwrap(), 1);
874        assert_eq!(observer_vectors.count().unwrap(), 1);
875        assert!(observer_catalog
876            .load_scoring_params("transactional")
877            .unwrap()
878            .is_some());
879    }
880
881    #[test]
882    fn ignored_legacy_index_error_cannot_commit_partial_document_write() {
883        let dir = tempfile::tempdir().unwrap();
884        let path = dir.path().join("ignored-index-error.sqlite3");
885        let conn = ManagedConnection::open(&path).unwrap();
886        let _catalog = Catalog::open(conn.clone()).unwrap();
887        let backend = SQLiteStorageBackend::new(conn.clone());
888        let observer = conn.new_session();
889        let mut docs = backend.document_store("articles");
890        let mut vectors = backend
891            .vector_index(
892                "articles",
893                "embedding",
894                2,
895                VectorIndexSpec::BruteForce,
896                VectorIndexOpenMode::Create,
897            )
898            .unwrap();
899
900        backend.begin_transaction().unwrap();
901        docs.put(
902            1,
903            BTreeMap::from([("title".to_string(), Value::Str("must roll back".into()))]),
904        )
905        .unwrap();
906        conn.with(|connection| {
907            connection.execute("DROP TABLE _vectors", [])?;
908            Ok(())
909        })
910        .unwrap();
911        // The vector write reports its error directly. Even if a caller
912        // ignores that Result, the managed transaction is poisoned and the
913        // partial document write cannot commit.
914        let ignored = vectors.add(1, vec![1.0, 0.0]);
915        assert!(ignored.is_err());
916        assert!(matches!(
917            backend.commit_transaction(),
918            Err(StorageBackendError::Backend { source, .. })
919                if matches!(source.downcast_ref::<SQLiteError>(), Some(SQLiteError::TransactionAborted(_)))
920        ));
921
922        let stored_docs: i64 = observer
923            .with(|connection| {
924                Ok(connection.query_row(
925                    "SELECT COUNT(*) FROM _documents WHERE table_name = 'articles'",
926                    [],
927                    |row| row.get(0),
928                )?)
929            })
930            .unwrap();
931        let vector_table_exists: i64 = observer
932            .with(|connection| {
933                Ok(connection.query_row(
934                    "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = '_vectors'",
935                    [],
936                    |row| row.get(0),
937                )?)
938            })
939            .unwrap();
940        assert_eq!(stored_docs, 0);
941        assert_eq!(vector_table_exists, 1);
942    }
943}