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