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