Skip to main content

uqa_storage_sqlite/
key_value.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `SQLite` persistence and connection affinity for common logical Key/Value sessions.
8
9use std::{path::Path, sync::Arc};
10
11use crate::{ManagedConnection, Result as SQLiteResult};
12use uqa_storage::mvcc::{StorageTransactionId, VersionedKeyValueStore, VersionedSessionOptions};
13use uqa_storage::read_control::{KeyValueReadVisitor, StorageReadControl, ValueReadVisitor};
14use uqa_storage::{
15    CatalogFacade, KeyValueBatch, KeyValueCatalog, KeyValueStorageBackend, KeyValueStore,
16    PersistentStorageBackend, PersistentStorageIdentity, PersistentStorageProvider,
17    PersistentStorageSession, StorageBackendResult,
18};
19
20/// A logical byte-store session sharing transaction state with its managed connection clones.
21#[derive(Clone)]
22pub struct SQLiteKeyValueStore {
23    conn: ManagedConnection,
24    records: Arc<VersionedKeyValueStore>,
25}
26
27impl SQLiteKeyValueStore {
28    pub fn open(path: &Path) -> SQLiteResult<Self> {
29        Self::new(ManagedConnection::open(path)?)
30    }
31
32    pub fn open_in_memory() -> SQLiteResult<Self> {
33        Self::new(ManagedConnection::open_in_memory()?)
34    }
35
36    pub fn new(conn: ManagedConnection) -> SQLiteResult<Self> {
37        Self::with_options(conn, VersionedSessionOptions::default())
38    }
39
40    /// Bind the connection and every existing clone to one bounded logical session.
41    pub fn with_options(
42        conn: ManagedConnection,
43        options: VersionedSessionOptions,
44    ) -> SQLiteResult<Self> {
45        let records = conn.bind_records(options)?;
46        Ok(Self { conn, records })
47    }
48
49    pub fn connection(&self) -> ManagedConnection {
50        self.conn.clone()
51    }
52
53    pub fn new_session(&self) -> Self {
54        self.new_session_with_cancellation(&uqa_core::CancellationToken::new())
55    }
56
57    pub fn new_session_with_cancellation(
58        &self,
59        cancellation: &uqa_core::CancellationToken,
60    ) -> Self {
61        let conn = self.conn.new_session_with_cancellation(cancellation);
62        let records = conn
63            .bind_records(self.records.options())
64            .expect("a fresh connection inherits the same logical session configuration");
65        Self { conn, records }
66    }
67
68    pub fn pending_commit(&self) -> Option<StorageTransactionId> {
69        self.records.pending_commit()
70    }
71}
72
73impl uqa_storage::mvcc::IdentifierAllocator for SQLiteKeyValueStore {
74    fn identifier_watermark(&self, namespace: &[u8]) -> StorageBackendResult<Option<u64>> {
75        self.conn
76            .with_records(|store| store.identifier_watermark(namespace))
77    }
78
79    fn allocate_identifiers(
80        &self,
81        namespace: &[u8],
82        request: uqa_storage::mvcc::IdentifierRequest,
83    ) -> StorageBackendResult<uqa_storage::mvcc::IdentifierAllocation> {
84        self.conn
85            .with_records(|store| store.allocate_identifiers(namespace, request))
86    }
87
88    fn observe_identifier(
89        &self,
90        namespace: &[u8],
91        value: u64,
92    ) -> StorageBackendResult<uqa_storage::mvcc::ObservedIdentifier> {
93        self.conn
94            .with_records(|store| store.observe_identifier(namespace, value))
95    }
96}
97
98impl KeyValueStore for SQLiteKeyValueStore {
99    fn resource_leases(&self) -> Option<&dyn uqa_storage::mvcc::ResourceLeaseProvider> {
100        self.records.resource_leases()
101    }
102
103    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
104        self.conn.auxiliary_encryption_key()
105    }
106
107    fn retention_control(&self) -> Option<uqa_storage::read_control::StorageReadControl> {
108        Some(self.records.retention_control())
109    }
110
111    fn notification_publications(
112        &self,
113    ) -> Option<&dyn uqa_storage::notifications::NotificationPublicationStore> {
114        Some(&self.conn)
115    }
116
117    fn serializable_session(&self) -> Option<&dyn uqa_storage::mvcc::SerializableSession> {
118        Some(&self.conn)
119    }
120
121    fn vacuum(&self) -> StorageBackendResult<()> {
122        self.conn.vacuum().map_err(Into::into)
123    }
124
125    fn reclaim_obsolete(&self) -> StorageBackendResult<()> {
126        self.conn.reclaim_obsolete().map_err(Into::into)
127    }
128
129    fn write_cancellation(&self) -> Option<uqa_core::CancellationToken> {
130        self.records.write_cancellation()
131    }
132
133    fn open_session_with_cancellation(
134        &self,
135        cancellation: &uqa_core::CancellationToken,
136    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
137        cancellation.check()?;
138        Ok(Arc::new(self.new_session_with_cancellation(cancellation)))
139    }
140
141    fn open_controlled_session(
142        &self,
143        control: &uqa_storage::read_control::StorageReadControl,
144    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
145        let conn = self.conn.new_controlled_session(control)?;
146        let records = conn.bind_records(self.records.options())?;
147        Ok(Arc::new(Self { conn, records }))
148    }
149
150    fn open_retained_read_session(
151        &self,
152        cancellation: &uqa_core::CancellationToken,
153    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
154        let conn = self.conn.new_retained_read_session(cancellation)?;
155        Ok(Arc::new(Self::with_options(conn, self.records.options())?))
156    }
157
158    fn capture_committed_read_boundary(
159        &self,
160    ) -> StorageBackendResult<Arc<uqa_storage::mvcc::CommittedReadBoundary>> {
161        self.conn.capture_committed_read_boundary()
162    }
163
164    fn open_read_session_with_private_changes(
165        &self,
166        boundary: &uqa_storage::mvcc::CommittedReadBoundary,
167        cancellation: &uqa_core::CancellationToken,
168    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
169        let conn = self
170            .conn
171            .new_read_session_with_private_changes(boundary, cancellation)?;
172        Ok(Arc::new(Self::with_options(conn, self.records.options())?))
173    }
174
175    fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
176        self.records.transaction_model()
177    }
178
179    fn refresh_transaction_snapshot(
180        &self,
181        cancellation: &uqa_core::CancellationToken,
182    ) -> StorageBackendResult<()> {
183        self.conn
184            .with_records(|store| store.refresh_transaction_snapshot(cancellation))
185    }
186
187    fn identifier_allocator(&self) -> Option<&dyn uqa_storage::mvcc::IdentifierAllocator> {
188        Some(self)
189    }
190
191    fn with_read_view(
192        &self,
193        read: &mut uqa_storage::key_value::KeyValueReadScope<'_>,
194    ) -> StorageBackendResult<()> {
195        self.conn.with_records(|store| store.with_read_view(read))
196    }
197
198    fn with_mutation(
199        &self,
200        mutate: &mut uqa_storage::key_value::KeyValueMutation<'_>,
201    ) -> StorageBackendResult<()> {
202        self.conn.with_records(|store| store.with_mutation(mutate))
203    }
204
205    fn with_versioned_mutation(
206        &self,
207        mutate: &mut uqa_storage::key_value::KeyValueVersionedMutation<'_>,
208    ) -> StorageBackendResult<()> {
209        self.conn
210            .with_records(|store| store.with_versioned_mutation(mutate))
211    }
212
213    fn with_mutation_revision(
214        &self,
215        prefixes: &[&[u8]],
216        mutate: &mut uqa_storage::key_value::KeyValueMutation<'_>,
217    ) -> StorageBackendResult<Option<uqa_storage::key_value::KeyValueReadRevision>> {
218        self.conn
219            .with_records(|store| store.with_mutation_revision(prefixes, mutate))
220    }
221
222    fn transaction_affinity(&self) -> Option<uqa_storage::StorageSessionAffinity> {
223        Some(self.records.session_affinity())
224    }
225
226    fn storage_identity(&self) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
227        self.records.storage_identity()
228    }
229
230    fn open_session(&self) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
231        Ok(Arc::new(self.new_session()))
232    }
233
234    fn get(&self, key: &[u8]) -> StorageBackendResult<Option<Vec<u8>>> {
235        self.conn.with_records(|store| store.get(key))
236    }
237
238    fn contains_key(&self, key: &[u8]) -> StorageBackendResult<bool> {
239        self.conn.with_records(|store| store.contains_key(key))
240    }
241
242    fn contains_prefix_budgeted(
243        &self,
244        prefix: &[u8],
245        control: &StorageReadControl,
246    ) -> StorageBackendResult<bool> {
247        self.conn
248            .with_records(|store| store.contains_prefix_budgeted(prefix, control))
249    }
250
251    fn visit_value(
252        &self,
253        key: &[u8],
254        control: &StorageReadControl,
255        visit: &mut ValueReadVisitor<'_>,
256    ) -> StorageBackendResult<()> {
257        self.conn
258            .with_records(|store| store.visit_value(key, control, visit))
259    }
260
261    fn visit_value_bounded(
262        &self,
263        key: &[u8],
264        max_bytes: usize,
265        control: &StorageReadControl,
266        visit: &mut ValueReadVisitor<'_>,
267    ) -> StorageBackendResult<()> {
268        self.conn
269            .with_records(|store| store.visit_value_bounded(key, max_bytes, control, visit))
270    }
271
272    fn visit_prefix_after(
273        &self,
274        prefix: &[u8],
275        after: Option<&[u8]>,
276        limit: usize,
277        control: &StorageReadControl,
278        visit: &mut KeyValueReadVisitor<'_>,
279    ) -> StorageBackendResult<()> {
280        self.conn
281            .with_records(|store| store.visit_prefix_after(prefix, after, limit, control, visit))
282    }
283
284    fn put(&self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
285        self.conn.with_records(|store| store.put(key, value))
286    }
287
288    fn delete(&self, key: &[u8]) -> StorageBackendResult<()> {
289        self.conn.with_records(|store| store.delete(key))
290    }
291
292    fn delete_prefix(&self, prefix: &[u8]) -> StorageBackendResult<usize> {
293        self.conn.with_records(|store| store.delete_prefix(prefix))
294    }
295
296    fn scan_prefix(&self, prefix: &[u8]) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>> {
297        self.conn.with_records(|store| store.scan_prefix(prefix))
298    }
299
300    fn scan_prefix_after(
301        &self,
302        prefix: &[u8],
303        after: Option<&[u8]>,
304        limit: usize,
305    ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>> {
306        self.conn
307            .with_records(|store| store.scan_prefix_after(prefix, after, limit))
308    }
309
310    fn scan_prefix_keys_after(
311        &self,
312        prefix: &[u8],
313        after: Option<&[u8]>,
314        limit: usize,
315    ) -> StorageBackendResult<Vec<Vec<u8>>> {
316        self.conn
317            .with_records(|store| store.scan_prefix_keys_after(prefix, after, limit))
318    }
319
320    fn first_prefix_after(
321        &self,
322        prefix: &[u8],
323        after: Option<&[u8]>,
324    ) -> StorageBackendResult<Option<(Vec<u8>, Vec<u8>)>> {
325        self.conn
326            .with_records(|store| store.first_prefix_after(prefix, after))
327    }
328
329    fn batch(&self) -> Box<dyn KeyValueBatch + '_> {
330        Box::new(SQLiteKeyValueBatch {
331            connection: &self.conn,
332            batch: self.records.batch(),
333        })
334    }
335
336    fn begin_transaction(&self) -> StorageBackendResult<()> {
337        self.conn.begin_transaction().map_err(Into::into)
338    }
339
340    fn begin_read_transaction(&self) -> StorageBackendResult<()> {
341        self.conn.begin_record_read().map_err(Into::into)
342    }
343
344    fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()> {
345        self.conn.begin_deferred_transaction().map_err(Into::into)
346    }
347
348    fn in_transaction(&self) -> bool {
349        self.conn.in_transaction()
350    }
351
352    fn transaction_has_written(&self) -> StorageBackendResult<bool> {
353        self.conn.transaction_has_written().map_err(Into::into)
354    }
355
356    fn change_version(&self) -> StorageBackendResult<Option<u64>> {
357        self.conn.data_version().map_err(Into::into)
358    }
359
360    fn read_view_revision(
361        &self,
362    ) -> StorageBackendResult<Option<uqa_storage::key_value::KeyValueReadRevision>> {
363        self.conn.read_view_revision().map_err(Into::into)
364    }
365
366    fn completed_commit(&self) -> Option<uqa_storage::mvcc::CommitReceipt> {
367        self.conn.completed_commit()
368    }
369
370    fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool> {
371        Ok(true)
372    }
373
374    fn pin_transaction_snapshot(&self) -> StorageBackendResult<()> {
375        self.conn.pin_transaction_snapshot().map_err(Into::into)
376    }
377
378    fn prepare_transaction_commit(&self) -> StorageBackendResult<()> {
379        self.conn.prepare_transaction_commit().map_err(Into::into)
380    }
381
382    fn commit_transaction(&self) -> StorageBackendResult<()> {
383        self.conn.commit_transaction().map_err(Into::into)
384    }
385
386    fn rollback_transaction(&self) -> StorageBackendResult<()> {
387        self.conn.rollback_transaction().map_err(Into::into)
388    }
389
390    fn savepoint(&self, name: &str) -> StorageBackendResult<()> {
391        self.conn.savepoint(name).map_err(Into::into)
392    }
393
394    fn release_savepoint(&self, name: &str) -> StorageBackendResult<()> {
395        self.conn.release_savepoint(name).map_err(Into::into)
396    }
397
398    fn rollback_to_savepoint(&self, name: &str) -> StorageBackendResult<()> {
399        self.conn.rollback_to_savepoint(name).map_err(Into::into)
400    }
401}
402
403struct SQLiteKeyValueBatch<'a> {
404    connection: &'a ManagedConnection,
405    batch: Box<dyn KeyValueBatch + 'a>,
406}
407
408impl KeyValueBatch for SQLiteKeyValueBatch<'_> {
409    fn serializable_participant(&self) -> Option<uqa_storage::mvcc::SerializableTransactionId> {
410        self.batch.serializable_participant()
411    }
412    fn put_unused(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
413        self.batch.put_unused(key, value)
414    }
415    fn observe_serializable_write(
416        &mut self,
417        predicate: uqa_storage::mvcc::SerializablePredicate<'_>,
418    ) -> StorageBackendResult<()> {
419        self.batch.observe_serializable_write(predicate)
420    }
421    fn require_unchanged(&mut self, key: &[u8]) -> StorageBackendResult<()> {
422        self.batch.require_unchanged(key)
423    }
424    fn require_observed(
425        &mut self,
426        key: &[u8],
427        revision: &uqa_storage::key_value::KeyValueReadRevision,
428    ) -> StorageBackendResult<()> {
429        self.batch.require_observed(key, revision)
430    }
431    fn put_observed(
432        &mut self,
433        key: &[u8],
434        value: &[u8],
435        revision: &uqa_storage::key_value::KeyValueReadRevision,
436    ) -> StorageBackendResult<()> {
437        self.batch.put_observed(key, value, revision)
438    }
439    fn put_with_retained_source(
440        &mut self,
441        key: &[u8],
442        value: &[u8],
443        source: Arc<dyn uqa_storage::key_value::KeyValueRead + Send + Sync>,
444    ) -> StorageBackendResult<()> {
445        self.batch.put_with_retained_source(key, value, source)
446    }
447    fn touch_marker(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
448        self.batch.touch_marker(key, value)
449    }
450    fn invalidate_diskann_origin(&mut self, key: &[u8]) -> StorageBackendResult<()> {
451        self.batch.invalidate_diskann_origin(key)
452    }
453    fn observe_identifier(&mut self, namespace: &[u8], value: u64) -> StorageBackendResult<()> {
454        self.batch.observe_identifier(namespace, value)
455    }
456    fn inherit_identifiers(&mut self, from: &[u8], to: &[u8]) -> StorageBackendResult<()> {
457        self.batch.inherit_identifiers(from, to)
458    }
459    fn ivf_mutation(
460        &mut self,
461        metadata: &[u8],
462        mutation: uqa_storage::ivf_index::IVFMutation<'_>,
463    ) -> StorageBackendResult<()> {
464        self.batch.ivf_mutation(metadata, mutation)
465    }
466    fn preview_ivf_record(&mut self, key: &[u8], value: Option<&[u8]>) -> StorageBackendResult<()> {
467        self.batch.preview_ivf_record(key, value)
468    }
469    fn preview_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
470        self.batch.preview_ivf_prefix(prefix)
471    }
472    fn fence_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
473        self.batch.fence_ivf_prefix(prefix)
474    }
475    fn hnsw_mutation(
476        &mut self,
477        metadata: &[u8],
478        mutation: uqa_storage::hnsw_index::HNSWMutation<'_>,
479    ) -> StorageBackendResult<()> {
480        self.batch.hnsw_mutation(metadata, mutation)
481    }
482    fn preview_hnsw_record(
483        &mut self,
484        key: &[u8],
485        value: Option<&[u8]>,
486    ) -> StorageBackendResult<()> {
487        self.batch.preview_hnsw_record(key, value)
488    }
489    fn preview_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
490        self.batch.preview_hnsw_prefix(prefix)
491    }
492    fn fence_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
493        self.batch.fence_hnsw_prefix(prefix)
494    }
495    fn put(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
496        self.batch.put(key, value)
497    }
498    fn replace_statistics_maintenance(
499        &mut self,
500        key: &[u8],
501        value: &[u8],
502    ) -> StorageBackendResult<()> {
503        self.batch.replace_statistics_maintenance(key, value)
504    }
505    fn delete(&mut self, key: &[u8]) -> StorageBackendResult<()> {
506        self.batch.delete(key)
507    }
508    fn delete_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
509        self.batch.delete_prefix(prefix)
510    }
511    fn replace_occurrence_record(
512        &mut self,
513        key: &[u8],
514        value: Option<&[u8]>,
515    ) -> StorageBackendResult<()> {
516        self.batch.replace_occurrence_record(key, value)
517    }
518    fn invalidate_occurrence_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
519        self.batch.invalidate_occurrence_prefix(prefix)
520    }
521    fn occurrence_document(&mut self, table: &str, document: u64) -> StorageBackendResult<()> {
522        self.batch.occurrence_document(table, document)
523    }
524    fn reset_occurrences(&mut self, table: &str) -> StorageBackendResult<()> {
525        self.batch.reset_occurrences(table)
526    }
527    fn fence_record(&mut self, key: &[u8]) -> StorageBackendResult<()> {
528        self.batch.fence_record(key)
529    }
530    fn graph_mutation(
531        &mut self,
532        mutation: uqa_storage::mvcc::GraphMutation<'_>,
533    ) -> StorageBackendResult<()> {
534        self.batch.graph_mutation(mutation)
535    }
536    fn preview_graph_invalidation(
537        &mut self,
538        key: &[u8],
539        value: Option<&[u8]>,
540    ) -> StorageBackendResult<()> {
541        self.batch.preview_graph_invalidation(key, value)
542    }
543    fn replace_graph_cache(
544        &mut self,
545        key: &[u8],
546        value: Option<&[u8]>,
547    ) -> StorageBackendResult<()> {
548        self.batch.replace_graph_cache(key, value)
549    }
550    fn commit(self: Box<Self>) -> StorageBackendResult<()> {
551        let Self { connection, batch } = *self;
552        connection.with_records(|_| batch.commit())
553    }
554}
555
556#[cfg(test)]
557#[path = "key_value/controlled/tests.rs"]
558mod controlled_tests;
559
560/// Shared `SQLite` `KeyValue` storage handle with catalog and backend factories.
561#[derive(Clone)]
562pub struct SQLiteKeyValueStorage {
563    store: Arc<SQLiteKeyValueStore>,
564}
565
566pub type SQLiteKeyValueCatalog = KeyValueCatalog;
567pub type SQLiteKeyValueStorageBackend = KeyValueStorageBackend;
568
569impl SQLiteKeyValueStorage {
570    pub fn open(path: &Path) -> SQLiteResult<Self> {
571        Self::open_with_options(path, VersionedSessionOptions::default())
572    }
573
574    pub fn open_with_options(path: &Path, options: VersionedSessionOptions) -> SQLiteResult<Self> {
575        Self::from_connection_with_options(ManagedConnection::open(path)?, options)
576    }
577
578    pub fn open_in_memory() -> SQLiteResult<Self> {
579        Ok(Self {
580            store: Arc::new(SQLiteKeyValueStore::open_in_memory()?),
581        })
582    }
583
584    pub fn from_connection(conn: ManagedConnection) -> SQLiteResult<Self> {
585        Self::from_connection_with_options(conn, VersionedSessionOptions::default())
586    }
587
588    pub fn from_connection_with_options(
589        conn: ManagedConnection,
590        options: VersionedSessionOptions,
591    ) -> SQLiteResult<Self> {
592        Ok(Self {
593            store: Arc::new(SQLiteKeyValueStore::with_options(conn, options)?),
594        })
595    }
596
597    pub fn store(&self) -> Arc<SQLiteKeyValueStore> {
598        Arc::clone(&self.store)
599    }
600
601    pub fn catalog(&self) -> SQLiteKeyValueCatalog {
602        let store: Arc<dyn KeyValueStore> = self.store.clone();
603        KeyValueCatalog::new(store)
604    }
605
606    pub fn backend(&self) -> SQLiteKeyValueStorageBackend {
607        let store: Arc<dyn KeyValueStore> = self.store.clone();
608        KeyValueStorageBackend::new(store)
609    }
610}
611
612impl PersistentStorageProvider for SQLiteKeyValueStorage {
613    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
614        self.store.conn.auxiliary_encryption_key()
615    }
616
617    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
618        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
619    }
620
621    fn open_session_with_cancellation(
622        &self,
623        cancellation: &uqa_core::CancellationToken,
624    ) -> StorageBackendResult<PersistentStorageSession> {
625        cancellation.check()?;
626        let store: Arc<dyn KeyValueStore> =
627            Arc::new(self.store.new_session_with_cancellation(cancellation));
628        let catalog: Arc<dyn CatalogFacade> = Arc::new(KeyValueCatalog::new(Arc::clone(&store)));
629        let backend: Arc<dyn PersistentStorageBackend> =
630            Arc::new(KeyValueStorageBackend::new(store));
631        Ok(PersistentStorageSession::new(catalog, backend))
632    }
633
634    fn storage_identity(
635        &self,
636    ) -> StorageBackendResult<Option<uqa_storage::PersistentStorageIdentity>> {
637        self.store.connection().storage_identity()
638    }
639}
640
641#[cfg(test)]
642mod tests {
643    use std::collections::BTreeMap;
644
645    use uqa_analysis::standard_analyzer;
646    use uqa_core::Value;
647    use uqa_storage::catalog::{ColumnStatsInput, TableSchema};
648    use uqa_storage::{
649        CatalogFacade, PersistentStorageBackend, VectorIndexOpenMode, VectorIndexSpec,
650    };
651
652    use super::*;
653
654    #[test]
655    fn mutation_revisions_preserve_sqlite_undo_and_failed_evaluation() {
656        let store = SQLiteKeyValueStore::open_in_memory().unwrap();
657        uqa_storage::key_value::conformance::verify_mutation_revisions(&store).unwrap();
658        uqa_storage::key_value::conformance::verify_mutation_revision_concurrency(
659            &store,
660            &store.new_session(),
661        )
662        .unwrap();
663    }
664
665    #[test]
666    fn foreign_server_metadata_preserves_snapshots_undo_and_reopen() {
667        use uqa_storage::key_value::conformance::{
668            verify_foreign_server_reopen, verify_foreign_server_rows,
669        };
670        let directory = tempfile::tempdir().unwrap();
671        let path = directory.path().join("foreign-servers.sqlite3");
672        {
673            let storage = SQLiteKeyValueStore::open(&path).unwrap();
674            let a: Arc<dyn KeyValueStore> = Arc::new(storage.new_session());
675            let b: Arc<dyn KeyValueStore> = Arc::new(storage.new_session());
676            verify_foreign_server_rows(&a, &b).unwrap();
677        }
678        let store: Arc<dyn KeyValueStore> = Arc::new(SQLiteKeyValueStore::open(&path).unwrap());
679        verify_foreign_server_reopen(&store).unwrap();
680    }
681
682    #[test]
683    fn sqlite_key_value_store_round_trips_and_reopens() {
684        let dir = tempfile::tempdir().unwrap();
685        let path = dir.path().join("keyvalue.sqlite3");
686        {
687            let store = SQLiteKeyValueStore::open(&path).unwrap();
688            store.put(b"apple/1", b"red").unwrap();
689            store.put(b"apple/2", b"green").unwrap();
690            store.put(b"banana/1", b"yellow").unwrap();
691            store.put(&[0x10, 0xff, 0x01], b"binary-prefix").unwrap();
692            store.put(&[0x11, 0x00], b"binary-neighbour").unwrap();
693            assert_eq!(store.get(b"apple/1").unwrap().as_deref(), Some(&b"red"[..]));
694            assert_eq!(store.scan_prefix(b"apple/").unwrap().len(), 2);
695            assert_eq!(
696                store
697                    .scan_prefix_keys_after(b"apple/", Some(b"apple/1"), 1)
698                    .unwrap(),
699                vec![b"apple/2".to_vec()]
700            );
701            assert_eq!(
702                store
703                    .scan_prefix_keys_after(b"apple/", Some(b"a"), 2)
704                    .unwrap(),
705                vec![b"apple/1".to_vec(), b"apple/2".to_vec()]
706            );
707            assert_eq!(
708                store
709                    .scan_prefix_keys_after(b"apple/", Some(b"z"), 2)
710                    .unwrap()
711                    .len(),
712                0
713            );
714            assert_eq!(
715                store.first_prefix_after(b"apple/", Some(b"a")).unwrap(),
716                Some((b"apple/1".to_vec(), b"red".to_vec()))
717            );
718            assert_eq!(
719                store
720                    .scan_prefix_keys_after(b"apple/", None, 0)
721                    .unwrap()
722                    .len(),
723                0
724            );
725            assert_eq!(store.scan_prefix(&[0x10, 0xff]).unwrap().len(), 1);
726            store.delete_prefix(&[0x10, 0xff]).unwrap();
727            assert_eq!(
728                store.get(&[0x11, 0x00]).unwrap().as_deref(),
729                Some(&b"binary-neighbour"[..])
730            );
731        }
732        {
733            let store = SQLiteKeyValueStore::open(&path).unwrap();
734            assert_eq!(
735                store.get(b"apple/2").unwrap().as_deref(),
736                Some(&b"green"[..])
737            );
738            store.delete_prefix(b"apple/").unwrap();
739            assert!(store.get(b"apple/1").unwrap().is_none());
740            assert_eq!(
741                store.get(b"banana/1").unwrap().as_deref(),
742                Some(&b"yellow"[..])
743            );
744        }
745    }
746
747    #[test]
748    fn sqlite_store_passes_the_reusable_backend_contract() {
749        let directory = tempfile::tempdir().unwrap();
750        let reader =
751            SQLiteKeyValueStore::open(&directory.path().join("conformance.sqlite3")).unwrap();
752        let writer = reader.new_session();
753        uqa_storage::key_value::conformance::verify_store(&reader).unwrap();
754        uqa_storage::key_value::conformance::verify_session_isolation(&reader, &writer).unwrap();
755    }
756
757    #[test]
758    fn sqlite_key_value_batch_is_atomic() {
759        let store = SQLiteKeyValueStore::open_in_memory().unwrap();
760        let mut batch = store.batch();
761        batch.put(b"k1", b"v1").unwrap();
762        batch.put(b"k2", b"v2").unwrap();
763        batch.commit().unwrap();
764        assert_eq!(store.get(b"k1").unwrap().as_deref(), Some(&b"v1"[..]));
765
766        store.begin_transaction().unwrap();
767        store.put(b"k3", b"v3").unwrap();
768        store.rollback_transaction().unwrap();
769        assert!(store.get(b"k3").unwrap().is_none());
770    }
771
772    #[test]
773    fn sqlite_key_value_storage_supports_existing_store_contracts() {
774        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
775        let backend = storage.backend();
776
777        let mut docs = backend.document_store("articles");
778        docs.put(
779            1,
780            BTreeMap::from([("title".to_string(), Value::Str("rust search".into()))]),
781        )
782        .unwrap();
783        assert_eq!(
784            docs.get_field(1, "title").unwrap(),
785            Some(Value::Str("rust search".into()))
786        );
787
788        let mut index = backend.inverted_index("articles", standard_analyzer("english"));
789        index
790            .add_document(1, BTreeMap::from([("title".into(), "rust search".into())]))
791            .unwrap();
792        assert_eq!(index.doc_freq("title", "rust").unwrap(), 1);
793
794        let mut vectors = backend
795            .vector_index(
796                "articles",
797                "embedding",
798                2,
799                VectorIndexSpec::BruteForce,
800                VectorIndexOpenMode::Create,
801            )
802            .unwrap();
803        vectors.add(1, vec![1.0, 0.0]).unwrap();
804        vectors.add(2, vec![0.0, 1.0]).unwrap();
805        let hits = vectors.search_knn(&[1.0, 0.0], 1).unwrap();
806        assert_eq!(hits.entries()[0].doc_id, 1);
807    }
808
809    #[test]
810    fn sqlite_key_value_catalog_supports_existing_registry_contracts() {
811        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
812        let catalog = storage.catalog();
813        catalog.set_metadata("schema_version", "keyvalue").unwrap();
814        catalog.save_schema("public").unwrap();
815        catalog
816            .save_table(&TableSchema {
817                relation: uqa_storage::RelationIdentity::new("public", "docs"),
818                security: uqa_storage::RelationSecurityRow::legacy("uqa"),
819                object_id: [1; 16],
820                storage_generation: [1; 16],
821                analyzer_json: "{}".into(),
822                fts_fields: vec!["title".into()],
823                vector_fields: Vec::new(),
824                columns_json: "[]".into(),
825                constraints_json: String::new(),
826            })
827            .unwrap();
828        catalog
829            .save_analyzer("ko", "{\"name\":\"standard\"}")
830            .unwrap();
831        catalog
832            .save_table_field_analyzer("docs", "title", "index", "ko")
833            .unwrap();
834        catalog
835            .save_foreign_server("fs", "memory", "{\"root\":\"/tmp\"}")
836            .unwrap();
837        catalog
838            .save_catalog_index(
839                &uqa_storage::RelationIdentity::new("public", "idx_docs_title"),
840                "gin",
841                "public.docs",
842                "[\"title\"]",
843                "{}",
844            )
845            .unwrap();
846        catalog
847            .save_column_stats(ColumnStatsInput::basic(
848                "docs",
849                "title",
850                4,
851                0,
852                Some("a"),
853                Some("z"),
854                10,
855            ))
856            .unwrap();
857
858        assert_eq!(
859            catalog.get_metadata("schema_version").unwrap().as_deref(),
860            Some("keyvalue")
861        );
862        assert_eq!(
863            catalog.load_tables().unwrap()[0].relation.qualified_name(),
864            "public.docs"
865        );
866        assert_eq!(catalog.load_analyzers().unwrap()[0].0, "ko");
867        assert_eq!(catalog.load_foreign_servers().unwrap()[0].0, "fs");
868        assert_eq!(
869            catalog.load_catalog_indexes().unwrap()[0]
870                .relation
871                .qualified_name(),
872            "public.idx_docs_title"
873        );
874        assert_eq!(
875            catalog.load_column_stats("docs").unwrap()[0].distinct_count,
876            4
877        );
878    }
879}