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
126impl PersistentStorageBackend for SQLiteStorageBackend {
127    fn retention_control(&self) -> Option<uqa_storage::read_control::StorageReadControl> {
128        self.conn.retention_control()
129    }
130
131    fn notification_publications(
132        &self,
133    ) -> Option<&dyn uqa_storage::notifications::NotificationPublicationStore> {
134        Some(&self.conn)
135    }
136
137    fn serializable_session(&self) -> Option<&dyn uqa_storage::mvcc::SerializableSession> {
138        self.conn
139            .is_native_record_session()
140            .then_some(&self.conn as &dyn uqa_storage::mvcc::SerializableSession)
141    }
142
143    fn open_retained_read_session(
144        &self,
145        cancellation: &uqa_core::CancellationToken,
146    ) -> StorageBackendResult<PersistentStorageSession> {
147        let connection = self.conn.new_retained_read_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 write_cancellation(&self) -> Option<uqa_core::CancellationToken> {
154        Some(self.conn.write_cancellation())
155    }
156
157    fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
158        self.conn.transaction_model()
159    }
160
161    fn identifier_allocator(&self) -> Option<&dyn uqa_storage::mvcc::IdentifierAllocator> {
162        self.conn.is_native_record_session().then_some(self)
163    }
164
165    fn transaction_affinity(&self) -> Option<uqa_storage::StorageSessionAffinity> {
166        Some(self.conn.transaction_affinity())
167    }
168
169    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
170        self.conn.auxiliary_encryption_key()
171    }
172
173    fn storage_identity(&self) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
174        self.conn.storage_identity()
175    }
176
177    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
178        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
179    }
180
181    fn open_session_with_cancellation(
182        &self,
183        cancellation: &uqa_core::CancellationToken,
184    ) -> StorageBackendResult<PersistentStorageSession> {
185        cancellation.check()?;
186        let connection = self.conn.new_session_with_cancellation(cancellation);
187        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
188        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
189        Ok(PersistentStorageSession::new(catalog, backend))
190    }
191
192    fn open_controlled_session(
193        &self,
194        control: &uqa_storage::read_control::StorageReadControl,
195    ) -> StorageBackendResult<PersistentStorageSession> {
196        let connection = self.conn.new_controlled_session(control)?;
197        let catalog: Arc<dyn CatalogFacade> = Arc::new(Catalog::open(connection.clone())?);
198        let backend: Arc<dyn PersistentStorageBackend> = Arc::new(Self::new(connection));
199        Ok(PersistentStorageSession::new(catalog, backend))
200    }
201
202    fn supports_concurrent_pinned_read_and_write(&self) -> bool {
203        self.conn.supports_concurrent_pinned_read_and_write()
204    }
205
206    fn document_store(&self, table: &str) -> Box<dyn DocumentStore> {
207        Box::new(SQLiteDocumentStore::new(self.conn.clone(), table))
208    }
209
210    fn inverted_index(&self, table: &str, analyzer: Analyzer) -> Box<dyn InvertedIndex> {
211        Box::new(SQLiteInvertedIndex::new(self.conn.clone(), table, analyzer))
212    }
213
214    fn vector_index(
215        &self,
216        table: &str,
217        field: &str,
218        dimensions: u32,
219        spec: VectorIndexSpec,
220        mode: VectorIndexOpenMode,
221    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
222        let index: Box<dyn VectorIndex> = match spec {
223            VectorIndexSpec::DiskANN(_) => {
224                return Err(uqa_storage::StorageBackendError::Other(
225                    "DiskANN requires an actual catalog binding".into(),
226                ))
227            }
228            VectorIndexSpec::BruteForce => Box::new(SQLiteVectorIndex::new(
229                self.conn.clone(),
230                table,
231                field,
232                dimensions,
233            )),
234            VectorIndexSpec::IVF(params) => {
235                params.validate()?;
236                match mode {
237                    VectorIndexOpenMode::Create => Box::new(SQLiteIVFIndex::with_params(
238                        self.conn.clone(),
239                        table,
240                        field,
241                        dimensions,
242                        params.nlist,
243                        params.nprobe,
244                        params.train_threshold,
245                    )),
246                    VectorIndexOpenMode::Restore => Box::new(SQLiteIVFIndex::open_existing(
247                        self.conn.clone(),
248                        table,
249                        field,
250                        dimensions,
251                        params.nlist,
252                        params.nprobe,
253                        params.train_threshold,
254                    )),
255                }
256            }
257            VectorIndexSpec::HNSW(params) => {
258                params.validate()?;
259                match mode {
260                    VectorIndexOpenMode::Create => Box::new(SQLiteHNSWIndex::with_params(
261                        self.conn.clone(),
262                        table,
263                        field,
264                        dimensions,
265                        params,
266                    )),
267                    VectorIndexOpenMode::Restore => {
268                        let index = SQLiteHNSWIndex::open_existing(
269                            self.conn.clone(),
270                            table,
271                            field,
272                            dimensions,
273                            params,
274                        );
275                        index.validate_existing()?;
276                        Box::new(index)
277                    }
278                }
279            }
280        };
281        Ok(index)
282    }
283
284    fn diskann_index(
285        &self,
286        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
287        options: uqa_storage::diskann_index::DiskANNIndexOptions,
288        temporary: &uqa_storage::diskann_index::build::DiskANNTemporaryBudget,
289        mode: VectorIndexOpenMode,
290    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
291        let canonical = crate::vector_index::SQLiteDiskANNCanonical::new(
292            self.conn.clone(),
293            binding.table,
294            binding.field,
295            binding.dimensions,
296        )?;
297        if mode == VectorIndexOpenMode::Create {
298            canonical.create_index(
299                binding.index,
300                &*binding.resolver,
301                options,
302                temporary,
303                binding.control,
304            )?;
305        }
306        let handle = canonical.bind(
307            binding.index.clone(),
308            binding.resolver,
309            options.read,
310            binding.control,
311        )?;
312        Ok(Box::new(
313            uqa_storage::diskann_index::PersistentDiskANNIndex::new(handle, options, temporary)?,
314        ))
315    }
316
317    fn diskann_journal_pruner(
318        &self,
319        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
320        max_record_bytes: usize,
321    ) -> StorageBackendResult<Box<dyn uqa_storage::diskann_index::changes::DiskANNJournalPruner>>
322    {
323        crate::vector_index::SQLiteDiskANNCanonical::new(
324            self.conn.clone(),
325            binding.table,
326            binding.field,
327            binding.dimensions,
328        )?
329        .journal_pruner(
330            binding.index,
331            binding.resolver,
332            max_record_bytes,
333            binding.control,
334        )
335    }
336
337    fn diskann_maintenance_source(
338        &self,
339        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
340        max_record_bytes: usize,
341    ) -> StorageBackendResult<
342        Box<dyn uqa_storage::diskann_index::maintenance::DiskANNMaintenanceSource>,
343    > {
344        crate::vector_index::SQLiteDiskANNCanonical::new(
345            self.conn.clone(),
346            binding.table,
347            binding.field,
348            binding.dimensions,
349        )?
350        .maintenance_source(
351            binding.index,
352            binding.resolver,
353            max_record_bytes,
354            binding.control,
355        )
356    }
357
358    fn retire_diskann_index(
359        &self,
360        binding: uqa_storage::diskann_index::DiskANNIndexBinding<'_>,
361    ) -> StorageBackendResult<()> {
362        crate::vector_index::SQLiteDiskANNCanonical::new(
363            self.conn.clone(),
364            binding.table,
365            binding.field,
366            binding.dimensions,
367        )?
368        .retire_index(binding.index, &*binding.resolver, binding.control)
369    }
370
371    fn drop_vector_index_metadata(&self, table: &str, field: &str) -> StorageBackendResult<()> {
372        SQLiteIVFIndex::drop_metadata(&self.conn, table, field)?;
373        SQLiteHNSWIndex::drop_metadata(&self.conn, table, field)?;
374        Ok(())
375    }
376
377    fn persists_btree_indexes(&self) -> bool {
378        true
379    }
380
381    fn load_btree_index(
382        &self,
383        table: &str,
384        field: &uqa_storage::ValueIndexKey,
385    ) -> StorageBackendResult<Option<Vec<(DocId, Value)>>> {
386        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).load(table, field)?)
387    }
388
389    fn btree_index_fields(
390        &self,
391        table: &str,
392    ) -> StorageBackendResult<Vec<uqa_storage::ValueIndexKey>> {
393        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).fields(table)?)
394    }
395
396    fn read_btree_index_entry(
397        &self,
398        table: &str,
399        field: &uqa_storage::ValueIndexKey,
400        doc_id: DocId,
401    ) -> StorageBackendResult<uqa_storage::ValueIndexEntry> {
402        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).read_entry(table, field, doc_id)?)
403    }
404
405    fn btree_index_repairs(
406        &self,
407    ) -> StorageBackendResult<Vec<(String, uqa_storage::ValueIndexKey)>> {
408        Ok(SQLiteBTreeIndexStore::new(self.conn.clone()).repairs()?)
409    }
410
411    fn clear_btree_index_repair(
412        &self,
413        table: &str,
414        field: &uqa_storage::ValueIndexKey,
415    ) -> StorageBackendResult<()> {
416        SQLiteBTreeIndexStore::new(self.conn.clone()).clear_repair(table, field)?;
417        Ok(())
418    }
419
420    fn replace_btree_index(
421        &self,
422        table: &str,
423        field: &uqa_storage::ValueIndexKey,
424        values: &[(DocId, Value)],
425    ) -> StorageBackendResult<()> {
426        SQLiteBTreeIndexStore::new(self.conn.clone()).replace(table, field, values)?;
427        Ok(())
428    }
429
430    fn repair_btree_index(
431        &self,
432        table: &str,
433        field: &uqa_storage::ValueIndexKey,
434        _complete: &[(DocId, Value)],
435        stale_doc_ids: &[DocId],
436        missing: &[(DocId, Value)],
437    ) -> StorageBackendResult<()> {
438        SQLiteBTreeIndexStore::new(self.conn.clone()).repair(
439            table,
440            field,
441            stale_doc_ids,
442            missing,
443        )?;
444        Ok(())
445    }
446
447    fn replace_btree_indexes(
448        &self,
449        table: &str,
450        indexes: &[(&uqa_storage::ValueIndexKey, &[(DocId, Value)])],
451    ) -> StorageBackendResult<()> {
452        SQLiteBTreeIndexStore::new(self.conn.clone()).replace_many(table, indexes)?;
453        Ok(())
454    }
455
456    fn apply_btree_index_write(
457        &self,
458        table: &str,
459        doc_id: DocId,
460        values: Option<&BTreeMap<uqa_storage::ValueIndexKey, Value>>,
461    ) -> StorageBackendResult<()> {
462        SQLiteBTreeIndexStore::new(self.conn.clone()).apply_write(table, doc_id, values)?;
463        Ok(())
464    }
465
466    fn drop_btree_index(
467        &self,
468        table: &str,
469        field: &uqa_storage::ValueIndexKey,
470    ) -> StorageBackendResult<()> {
471        SQLiteBTreeIndexStore::new(self.conn.clone()).drop_index(table, field)?;
472        Ok(())
473    }
474
475    fn clear_btree_indexes(&self, table: &str) -> StorageBackendResult<()> {
476        SQLiteBTreeIndexStore::new(self.conn.clone()).clear_table(table)?;
477        Ok(())
478    }
479
480    fn vacuum(&self) -> StorageBackendResult<()> {
481        self.conn.vacuum()?;
482        Ok(())
483    }
484
485    fn reclaim_obsolete(&self) -> StorageBackendResult<()> {
486        self.conn.reclaim_obsolete().map_err(Into::into)
487    }
488
489    fn begin_transaction(&self) -> StorageBackendResult<()> {
490        self.conn.begin_transaction()?;
491        Ok(())
492    }
493
494    fn begin_read_transaction(&self) -> StorageBackendResult<()> {
495        self.conn.begin_deferred_transaction()?;
496        Ok(())
497    }
498
499    fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()> {
500        if self.native_initial_restore && !self.conn.is_native_record_session() {
501            self.conn.begin_native_initial_restore()?;
502        } else {
503            self.conn.begin_deferred_transaction()?;
504        }
505        Ok(())
506    }
507
508    fn refresh_transaction_snapshot(
509        &self,
510        cancellation: &uqa_core::CancellationToken,
511    ) -> StorageBackendResult<()> {
512        self.conn.refresh_transaction_snapshot(cancellation)?;
513        Ok(())
514    }
515
516    fn in_transaction(&self) -> bool {
517        self.conn.in_transaction()
518    }
519
520    fn transaction_has_written(&self) -> StorageBackendResult<bool> {
521        Ok(self.conn.transaction_has_written()?)
522    }
523
524    fn change_version(&self) -> StorageBackendResult<Option<u64>> {
525        Ok(self.conn.data_version()?)
526    }
527
528    fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool> {
529        Ok(self.conn.data_version_monitor_is_nonblocking()?)
530    }
531
532    fn pin_transaction_snapshot(&self) -> StorageBackendResult<()> {
533        self.conn.pin_transaction_snapshot()?;
534        Ok(())
535    }
536
537    fn commit_transaction(&self) -> StorageBackendResult<()> {
538        self.conn.commit_transaction()?;
539        Ok(())
540    }
541
542    fn rollback_transaction(&self) -> StorageBackendResult<()> {
543        self.conn.rollback_transaction()?;
544        Ok(())
545    }
546
547    fn savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
548        self.conn.savepoint(&id.backend_name())?;
549        Ok(())
550    }
551
552    fn release_savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
553        self.conn.release_savepoint(&id.backend_name())?;
554        Ok(())
555    }
556
557    fn rollback_to_savepoint(&self, id: StorageSavepointId) -> StorageBackendResult<()> {
558        self.conn.rollback_to_savepoint(&id.backend_name())?;
559        Ok(())
560    }
561}
562
563#[cfg(test)]
564mod tests {
565    use std::collections::BTreeMap;
566
567    use uqa_analysis::analyzer::standard_analyzer;
568    use uqa_core::Value;
569    use uqa_storage::StorageBackendError;
570
571    use super::*;
572    use crate::{Catalog, SQLiteError};
573
574    #[test]
575    fn session_factories_preserve_a_bound_native_sessions_retention_options() {
576        let connection = ManagedConnection::open_in_memory().unwrap();
577        connection
578            .bind_native_records(uqa_storage::mvcc::VersionedSessionOptions {
579                retained_bytes: 8 << 20,
580            })
581            .unwrap();
582        let provider = SQLiteStorageProvider::new(connection);
583        let initial = provider.open_initial_session().unwrap();
584        let sibling = provider.open_session().unwrap();
585        initial.validate_transaction_affinity().unwrap();
586        sibling.validate_transaction_affinity().unwrap();
587        assert!(initial.backend.transaction_model().is_versioned());
588        assert_eq!(
589            initial.backend.transaction_model(),
590            sibling.backend.transaction_model()
591        );
592        assert_ne!(
593            initial.backend.transaction_affinity(),
594            sibling.backend.transaction_affinity()
595        );
596    }
597
598    #[test]
599    fn session_factory_reads_current_catalog_while_a_sibling_holds_a_writer_reservation() {
600        let directory = tempfile::tempdir().unwrap();
601        let connection = ManagedConnection::open_compressed(
602            &directory.path().join("session-writer-reservation.db"),
603            crate::SQLiteCompressionOptions::default(),
604        )
605        .unwrap();
606        let provider = SQLiteStorageProvider::new(connection);
607        let writer = provider.open_session().unwrap();
608        writer.backend.begin_transaction().unwrap();
609        writer
610            .catalog
611            .set_metadata("private-write", "uncommitted")
612            .unwrap();
613
614        let reader = provider.open_session().unwrap();
615        assert_eq!(reader.catalog.get_metadata("private-write").unwrap(), None);
616        writer.backend.commit_transaction().unwrap();
617        assert_eq!(
618            reader
619                .catalog
620                .get_metadata("private-write")
621                .unwrap()
622                .as_deref(),
623            Some("uncommitted")
624        );
625    }
626
627    #[test]
628    fn sqlite_backend_builds_document_index_and_vector_stores() {
629        let conn = ManagedConnection::open_in_memory().unwrap();
630        let _catalog = Catalog::open(conn.clone()).unwrap();
631        let backend = SQLiteStorageBackend::new(conn);
632
633        let mut doc = BTreeMap::new();
634        doc.insert("title".to_string(), Value::Str("rust storage".into()));
635        let mut docs = backend.document_store("articles");
636        docs.put(1, doc).unwrap();
637        assert_eq!(
638            docs.get_field(1, "title").unwrap(),
639            Some(Value::Str("rust storage".into()))
640        );
641
642        let mut inv = backend.inverted_index("articles", standard_analyzer("english"));
643        inv.add_document(
644            1,
645            BTreeMap::from([("title".to_string(), "rust storage".to_string())]),
646        )
647        .unwrap();
648        assert_eq!(inv.doc_freq("title", "rust").unwrap(), 1);
649
650        let mut vectors = backend
651            .vector_index(
652                "articles",
653                "embedding",
654                2,
655                VectorIndexSpec::IVF(uqa_storage::IVFIndexParams {
656                    nlist: 2,
657                    nprobe: 1,
658                    train_threshold: 2,
659                }),
660                VectorIndexOpenMode::Create,
661            )
662            .unwrap();
663        vectors.add(1, vec![1.0, 0.0]).unwrap();
664        let hits = vectors.search_knn(&[1.0, 0.0], 1).unwrap();
665        assert_eq!(hits.entries().len(), 1);
666        assert_eq!(hits.entries()[0].doc_id, 1);
667    }
668
669    #[test]
670    fn sqlite_backend_transaction_rolls_back_cross_store_writes() {
671        let conn = ManagedConnection::open_in_memory().unwrap();
672        let _catalog = Catalog::open(conn.clone()).unwrap();
673        let backend = SQLiteStorageBackend::new(conn);
674        let mut docs = backend.document_store("articles");
675        let mut inv = backend.inverted_index("articles", standard_analyzer("english"));
676
677        backend.begin_transaction().unwrap();
678        docs.put(
679            1,
680            BTreeMap::from([("title".to_string(), Value::Str("rollback".into()))]),
681        )
682        .unwrap();
683        inv.add_document(
684            1,
685            BTreeMap::from([("title".to_string(), "rollback".to_string())]),
686        )
687        .unwrap();
688        backend.rollback_transaction().unwrap();
689
690        assert_eq!(docs.len().unwrap(), 0);
691        assert_eq!(inv.doc_freq("title", "rollback").unwrap(), 0);
692    }
693
694    #[test]
695    fn sqlite_sessions_isolate_and_atomically_commit_cross_store_writes() {
696        let dir = tempfile::tempdir().unwrap();
697        let path = dir.path().join("cross-store-isolation.sqlite3");
698        let conn = ManagedConnection::open(&path).unwrap();
699        let catalog = Catalog::open(conn.clone()).unwrap();
700        let writer = SQLiteStorageBackend::new(conn.clone());
701        let observer_conn = conn.new_session();
702        let observer_catalog = Catalog::open(observer_conn.clone()).unwrap();
703        let observer = SQLiteStorageBackend::new(observer_conn);
704
705        let mut writer_docs = writer.document_store("articles");
706        let mut writer_inv = writer.inverted_index("articles", standard_analyzer("english"));
707        let mut writer_vectors = writer
708            .vector_index(
709                "articles",
710                "embedding",
711                2,
712                VectorIndexSpec::BruteForce,
713                VectorIndexOpenMode::Create,
714            )
715            .unwrap();
716        let observer_docs = observer.document_store("articles");
717        let observer_inv = observer.inverted_index("articles", standard_analyzer("english"));
718        let observer_vectors = observer
719            .vector_index(
720                "articles",
721                "embedding",
722                2,
723                VectorIndexSpec::BruteForce,
724                VectorIndexOpenMode::Restore,
725            )
726            .unwrap();
727
728        writer.begin_transaction().unwrap();
729        writer_docs
730            .put(
731                1,
732                BTreeMap::from([("title".to_string(), Value::Str("atomic rust".into()))]),
733            )
734            .unwrap();
735        writer_inv
736            .add_document(
737                1,
738                BTreeMap::from([("title".to_string(), "atomic rust".to_string())]),
739            )
740            .unwrap();
741        writer_vectors.add(1, vec![1.0, 0.0]).unwrap();
742        catalog
743            .save_scoring_params("transactional", r#"{"alpha":1.0}"#)
744            .unwrap();
745
746        assert_eq!(writer_docs.len().unwrap(), 1);
747        assert_eq!(writer_inv.doc_freq("title", "rust").unwrap(), 1);
748        assert_eq!(writer_vectors.count().unwrap(), 1);
749        assert!(catalog
750            .load_scoring_params("transactional")
751            .unwrap()
752            .is_some());
753
754        assert_eq!(observer_docs.len().unwrap(), 0);
755        assert_eq!(observer_inv.doc_freq("title", "rust").unwrap(), 0);
756        assert_eq!(observer_vectors.count().unwrap(), 0);
757        assert!(observer_catalog
758            .load_scoring_params("transactional")
759            .unwrap()
760            .is_none());
761
762        writer.commit_transaction().unwrap();
763        assert_eq!(observer_docs.len().unwrap(), 1);
764        assert_eq!(observer_inv.doc_freq("title", "rust").unwrap(), 1);
765        assert_eq!(observer_vectors.count().unwrap(), 1);
766        assert!(observer_catalog
767            .load_scoring_params("transactional")
768            .unwrap()
769            .is_some());
770    }
771
772    #[test]
773    fn ignored_legacy_index_error_cannot_commit_partial_document_write() {
774        let dir = tempfile::tempdir().unwrap();
775        let path = dir.path().join("ignored-index-error.sqlite3");
776        let conn = ManagedConnection::open(&path).unwrap();
777        let _catalog = Catalog::open(conn.clone()).unwrap();
778        let backend = SQLiteStorageBackend::new(conn.clone());
779        let observer = conn.new_session();
780        let mut docs = backend.document_store("articles");
781        let mut vectors = backend
782            .vector_index(
783                "articles",
784                "embedding",
785                2,
786                VectorIndexSpec::BruteForce,
787                VectorIndexOpenMode::Create,
788            )
789            .unwrap();
790
791        backend.begin_transaction().unwrap();
792        docs.put(
793            1,
794            BTreeMap::from([("title".to_string(), Value::Str("must roll back".into()))]),
795        )
796        .unwrap();
797        conn.with(|connection| {
798            connection.execute("DROP TABLE _vectors", [])?;
799            Ok(())
800        })
801        .unwrap();
802        // The vector write reports its error directly. Even if a caller
803        // ignores that Result, the managed transaction is poisoned and the
804        // partial document write cannot commit.
805        let ignored = vectors.add(1, vec![1.0, 0.0]);
806        assert!(ignored.is_err());
807        assert!(matches!(
808            backend.commit_transaction(),
809            Err(StorageBackendError::Backend { source, .. })
810                if matches!(source.downcast_ref::<SQLiteError>(), Some(SQLiteError::TransactionAborted(_)))
811        ));
812
813        let stored_docs: i64 = observer
814            .with(|connection| {
815                Ok(connection.query_row(
816                    "SELECT COUNT(*) FROM _documents WHERE table_name = 'articles'",
817                    [],
818                    |row| row.get(0),
819                )?)
820            })
821            .unwrap();
822        let vector_table_exists: i64 = observer
823            .with(|connection| {
824                Ok(connection.query_row(
825                    "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = '_vectors'",
826                    [],
827                    |row| row.get(0),
828                )?)
829            })
830            .unwrap();
831        assert_eq!(stored_docs, 0);
832        assert_eq!(vector_table_exists, 1);
833    }
834}