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 commit_transaction(&self) -> StorageBackendResult<()> {
379        self.conn.commit_transaction().map_err(Into::into)
380    }
381
382    fn rollback_transaction(&self) -> StorageBackendResult<()> {
383        self.conn.rollback_transaction().map_err(Into::into)
384    }
385
386    fn savepoint(&self, name: &str) -> StorageBackendResult<()> {
387        self.conn.savepoint(name).map_err(Into::into)
388    }
389
390    fn release_savepoint(&self, name: &str) -> StorageBackendResult<()> {
391        self.conn.release_savepoint(name).map_err(Into::into)
392    }
393
394    fn rollback_to_savepoint(&self, name: &str) -> StorageBackendResult<()> {
395        self.conn.rollback_to_savepoint(name).map_err(Into::into)
396    }
397}
398
399struct SQLiteKeyValueBatch<'a> {
400    connection: &'a ManagedConnection,
401    batch: Box<dyn KeyValueBatch + 'a>,
402}
403
404impl KeyValueBatch for SQLiteKeyValueBatch<'_> {
405    fn serializable_participant(&self) -> Option<uqa_storage::mvcc::SerializableTransactionId> {
406        self.batch.serializable_participant()
407    }
408    fn put_unused(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
409        self.batch.put_unused(key, value)
410    }
411    fn observe_serializable_write(
412        &mut self,
413        predicate: uqa_storage::mvcc::SerializablePredicate<'_>,
414    ) -> StorageBackendResult<()> {
415        self.batch.observe_serializable_write(predicate)
416    }
417    fn require_unchanged(&mut self, key: &[u8]) -> StorageBackendResult<()> {
418        self.batch.require_unchanged(key)
419    }
420    fn require_observed(
421        &mut self,
422        key: &[u8],
423        revision: &uqa_storage::key_value::KeyValueReadRevision,
424    ) -> StorageBackendResult<()> {
425        self.batch.require_observed(key, revision)
426    }
427    fn put_observed(
428        &mut self,
429        key: &[u8],
430        value: &[u8],
431        revision: &uqa_storage::key_value::KeyValueReadRevision,
432    ) -> StorageBackendResult<()> {
433        self.batch.put_observed(key, value, revision)
434    }
435    fn put_with_retained_source(
436        &mut self,
437        key: &[u8],
438        value: &[u8],
439        source: Arc<dyn uqa_storage::key_value::KeyValueRead + Send + Sync>,
440    ) -> StorageBackendResult<()> {
441        self.batch.put_with_retained_source(key, value, source)
442    }
443    fn touch_marker(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
444        self.batch.touch_marker(key, value)
445    }
446    fn invalidate_diskann_origin(&mut self, key: &[u8]) -> StorageBackendResult<()> {
447        self.batch.invalidate_diskann_origin(key)
448    }
449    fn observe_identifier(&mut self, namespace: &[u8], value: u64) -> StorageBackendResult<()> {
450        self.batch.observe_identifier(namespace, value)
451    }
452    fn inherit_identifiers(&mut self, from: &[u8], to: &[u8]) -> StorageBackendResult<()> {
453        self.batch.inherit_identifiers(from, to)
454    }
455    fn ivf_mutation(
456        &mut self,
457        metadata: &[u8],
458        mutation: uqa_storage::ivf_index::IVFMutation<'_>,
459    ) -> StorageBackendResult<()> {
460        self.batch.ivf_mutation(metadata, mutation)
461    }
462    fn preview_ivf_record(&mut self, key: &[u8], value: Option<&[u8]>) -> StorageBackendResult<()> {
463        self.batch.preview_ivf_record(key, value)
464    }
465    fn preview_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
466        self.batch.preview_ivf_prefix(prefix)
467    }
468    fn fence_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
469        self.batch.fence_ivf_prefix(prefix)
470    }
471    fn hnsw_mutation(
472        &mut self,
473        metadata: &[u8],
474        mutation: uqa_storage::hnsw_index::HNSWMutation<'_>,
475    ) -> StorageBackendResult<()> {
476        self.batch.hnsw_mutation(metadata, mutation)
477    }
478    fn preview_hnsw_record(
479        &mut self,
480        key: &[u8],
481        value: Option<&[u8]>,
482    ) -> StorageBackendResult<()> {
483        self.batch.preview_hnsw_record(key, value)
484    }
485    fn preview_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
486        self.batch.preview_hnsw_prefix(prefix)
487    }
488    fn fence_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
489        self.batch.fence_hnsw_prefix(prefix)
490    }
491    fn put(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
492        self.batch.put(key, value)
493    }
494    fn replace_statistics_maintenance(
495        &mut self,
496        key: &[u8],
497        value: &[u8],
498    ) -> StorageBackendResult<()> {
499        self.batch.replace_statistics_maintenance(key, value)
500    }
501    fn delete(&mut self, key: &[u8]) -> StorageBackendResult<()> {
502        self.batch.delete(key)
503    }
504    fn delete_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
505        self.batch.delete_prefix(prefix)
506    }
507    fn replace_occurrence_record(
508        &mut self,
509        key: &[u8],
510        value: Option<&[u8]>,
511    ) -> StorageBackendResult<()> {
512        self.batch.replace_occurrence_record(key, value)
513    }
514    fn invalidate_occurrence_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
515        self.batch.invalidate_occurrence_prefix(prefix)
516    }
517    fn occurrence_document(&mut self, table: &str, document: u64) -> StorageBackendResult<()> {
518        self.batch.occurrence_document(table, document)
519    }
520    fn reset_occurrences(&mut self, table: &str) -> StorageBackendResult<()> {
521        self.batch.reset_occurrences(table)
522    }
523    fn fence_record(&mut self, key: &[u8]) -> StorageBackendResult<()> {
524        self.batch.fence_record(key)
525    }
526    fn graph_mutation(
527        &mut self,
528        mutation: uqa_storage::mvcc::GraphMutation<'_>,
529    ) -> StorageBackendResult<()> {
530        self.batch.graph_mutation(mutation)
531    }
532    fn preview_graph_invalidation(
533        &mut self,
534        key: &[u8],
535        value: Option<&[u8]>,
536    ) -> StorageBackendResult<()> {
537        self.batch.preview_graph_invalidation(key, value)
538    }
539    fn replace_graph_cache(
540        &mut self,
541        key: &[u8],
542        value: Option<&[u8]>,
543    ) -> StorageBackendResult<()> {
544        self.batch.replace_graph_cache(key, value)
545    }
546    fn commit(self: Box<Self>) -> StorageBackendResult<()> {
547        let Self { connection, batch } = *self;
548        connection.with_records(|_| batch.commit())
549    }
550}
551
552#[cfg(test)]
553#[path = "key_value/controlled/tests.rs"]
554mod controlled_tests;
555
556/// Shared `SQLite` `KeyValue` storage handle with catalog and backend factories.
557#[derive(Clone)]
558pub struct SQLiteKeyValueStorage {
559    store: Arc<SQLiteKeyValueStore>,
560}
561
562pub type SQLiteKeyValueCatalog = KeyValueCatalog;
563pub type SQLiteKeyValueStorageBackend = KeyValueStorageBackend;
564
565impl SQLiteKeyValueStorage {
566    pub fn open(path: &Path) -> SQLiteResult<Self> {
567        Self::open_with_options(path, VersionedSessionOptions::default())
568    }
569
570    pub fn open_with_options(path: &Path, options: VersionedSessionOptions) -> SQLiteResult<Self> {
571        Self::from_connection_with_options(ManagedConnection::open(path)?, options)
572    }
573
574    pub fn open_in_memory() -> SQLiteResult<Self> {
575        Ok(Self {
576            store: Arc::new(SQLiteKeyValueStore::open_in_memory()?),
577        })
578    }
579
580    pub fn from_connection(conn: ManagedConnection) -> SQLiteResult<Self> {
581        Self::from_connection_with_options(conn, VersionedSessionOptions::default())
582    }
583
584    pub fn from_connection_with_options(
585        conn: ManagedConnection,
586        options: VersionedSessionOptions,
587    ) -> SQLiteResult<Self> {
588        Ok(Self {
589            store: Arc::new(SQLiteKeyValueStore::with_options(conn, options)?),
590        })
591    }
592
593    pub fn store(&self) -> Arc<SQLiteKeyValueStore> {
594        Arc::clone(&self.store)
595    }
596
597    pub fn catalog(&self) -> SQLiteKeyValueCatalog {
598        let store: Arc<dyn KeyValueStore> = self.store.clone();
599        KeyValueCatalog::new(store)
600    }
601
602    pub fn backend(&self) -> SQLiteKeyValueStorageBackend {
603        let store: Arc<dyn KeyValueStore> = self.store.clone();
604        KeyValueStorageBackend::new(store)
605    }
606}
607
608impl PersistentStorageProvider for SQLiteKeyValueStorage {
609    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
610        self.store.conn.auxiliary_encryption_key()
611    }
612
613    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
614        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
615    }
616
617    fn open_session_with_cancellation(
618        &self,
619        cancellation: &uqa_core::CancellationToken,
620    ) -> StorageBackendResult<PersistentStorageSession> {
621        cancellation.check()?;
622        let store: Arc<dyn KeyValueStore> =
623            Arc::new(self.store.new_session_with_cancellation(cancellation));
624        let catalog: Arc<dyn CatalogFacade> = Arc::new(KeyValueCatalog::new(Arc::clone(&store)));
625        let backend: Arc<dyn PersistentStorageBackend> =
626            Arc::new(KeyValueStorageBackend::new(store));
627        Ok(PersistentStorageSession::new(catalog, backend))
628    }
629
630    fn storage_identity(
631        &self,
632    ) -> StorageBackendResult<Option<uqa_storage::PersistentStorageIdentity>> {
633        self.store.connection().storage_identity()
634    }
635}
636
637#[cfg(test)]
638mod tests {
639    use std::collections::BTreeMap;
640
641    use uqa_analysis::standard_analyzer;
642    use uqa_core::Value;
643    use uqa_storage::catalog::{ColumnStatsInput, TableSchema};
644    use uqa_storage::{
645        CatalogFacade, PersistentStorageBackend, VectorIndexOpenMode, VectorIndexSpec,
646    };
647
648    use super::*;
649
650    #[test]
651    fn mutation_revisions_preserve_sqlite_undo_and_failed_evaluation() {
652        let store = SQLiteKeyValueStore::open_in_memory().unwrap();
653        uqa_storage::key_value::conformance::verify_mutation_revisions(&store).unwrap();
654        uqa_storage::key_value::conformance::verify_mutation_revision_concurrency(
655            &store,
656            &store.new_session(),
657        )
658        .unwrap();
659    }
660
661    #[test]
662    fn foreign_server_metadata_preserves_snapshots_undo_and_reopen() {
663        use uqa_storage::key_value::conformance::{
664            verify_foreign_server_reopen, verify_foreign_server_rows,
665        };
666        let directory = tempfile::tempdir().unwrap();
667        let path = directory.path().join("foreign-servers.sqlite3");
668        {
669            let storage = SQLiteKeyValueStore::open(&path).unwrap();
670            let a: Arc<dyn KeyValueStore> = Arc::new(storage.new_session());
671            let b: Arc<dyn KeyValueStore> = Arc::new(storage.new_session());
672            verify_foreign_server_rows(&a, &b).unwrap();
673        }
674        let store: Arc<dyn KeyValueStore> = Arc::new(SQLiteKeyValueStore::open(&path).unwrap());
675        verify_foreign_server_reopen(&store).unwrap();
676    }
677
678    #[test]
679    fn sqlite_key_value_store_round_trips_and_reopens() {
680        let dir = tempfile::tempdir().unwrap();
681        let path = dir.path().join("keyvalue.sqlite3");
682        {
683            let store = SQLiteKeyValueStore::open(&path).unwrap();
684            store.put(b"apple/1", b"red").unwrap();
685            store.put(b"apple/2", b"green").unwrap();
686            store.put(b"banana/1", b"yellow").unwrap();
687            store.put(&[0x10, 0xff, 0x01], b"binary-prefix").unwrap();
688            store.put(&[0x11, 0x00], b"binary-neighbour").unwrap();
689            assert_eq!(store.get(b"apple/1").unwrap().as_deref(), Some(&b"red"[..]));
690            assert_eq!(store.scan_prefix(b"apple/").unwrap().len(), 2);
691            assert_eq!(
692                store
693                    .scan_prefix_keys_after(b"apple/", Some(b"apple/1"), 1)
694                    .unwrap(),
695                vec![b"apple/2".to_vec()]
696            );
697            assert_eq!(
698                store
699                    .scan_prefix_keys_after(b"apple/", Some(b"a"), 2)
700                    .unwrap(),
701                vec![b"apple/1".to_vec(), b"apple/2".to_vec()]
702            );
703            assert_eq!(
704                store
705                    .scan_prefix_keys_after(b"apple/", Some(b"z"), 2)
706                    .unwrap()
707                    .len(),
708                0
709            );
710            assert_eq!(
711                store.first_prefix_after(b"apple/", Some(b"a")).unwrap(),
712                Some((b"apple/1".to_vec(), b"red".to_vec()))
713            );
714            assert_eq!(
715                store
716                    .scan_prefix_keys_after(b"apple/", None, 0)
717                    .unwrap()
718                    .len(),
719                0
720            );
721            assert_eq!(store.scan_prefix(&[0x10, 0xff]).unwrap().len(), 1);
722            store.delete_prefix(&[0x10, 0xff]).unwrap();
723            assert_eq!(
724                store.get(&[0x11, 0x00]).unwrap().as_deref(),
725                Some(&b"binary-neighbour"[..])
726            );
727        }
728        {
729            let store = SQLiteKeyValueStore::open(&path).unwrap();
730            assert_eq!(
731                store.get(b"apple/2").unwrap().as_deref(),
732                Some(&b"green"[..])
733            );
734            store.delete_prefix(b"apple/").unwrap();
735            assert!(store.get(b"apple/1").unwrap().is_none());
736            assert_eq!(
737                store.get(b"banana/1").unwrap().as_deref(),
738                Some(&b"yellow"[..])
739            );
740        }
741    }
742
743    #[test]
744    fn sqlite_store_passes_the_reusable_backend_contract() {
745        let directory = tempfile::tempdir().unwrap();
746        let reader =
747            SQLiteKeyValueStore::open(&directory.path().join("conformance.sqlite3")).unwrap();
748        let writer = reader.new_session();
749        uqa_storage::key_value::conformance::verify_store(&reader).unwrap();
750        uqa_storage::key_value::conformance::verify_session_isolation(&reader, &writer).unwrap();
751    }
752
753    #[test]
754    fn sqlite_key_value_batch_is_atomic() {
755        let store = SQLiteKeyValueStore::open_in_memory().unwrap();
756        let mut batch = store.batch();
757        batch.put(b"k1", b"v1").unwrap();
758        batch.put(b"k2", b"v2").unwrap();
759        batch.commit().unwrap();
760        assert_eq!(store.get(b"k1").unwrap().as_deref(), Some(&b"v1"[..]));
761
762        store.begin_transaction().unwrap();
763        store.put(b"k3", b"v3").unwrap();
764        store.rollback_transaction().unwrap();
765        assert!(store.get(b"k3").unwrap().is_none());
766    }
767
768    #[test]
769    fn sqlite_key_value_storage_supports_existing_store_contracts() {
770        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
771        let backend = storage.backend();
772
773        let mut docs = backend.document_store("articles");
774        docs.put(
775            1,
776            BTreeMap::from([("title".to_string(), Value::Str("rust search".into()))]),
777        )
778        .unwrap();
779        assert_eq!(
780            docs.get_field(1, "title").unwrap(),
781            Some(Value::Str("rust search".into()))
782        );
783
784        let mut index = backend.inverted_index("articles", standard_analyzer("english"));
785        index
786            .add_document(1, BTreeMap::from([("title".into(), "rust search".into())]))
787            .unwrap();
788        assert_eq!(index.doc_freq("title", "rust").unwrap(), 1);
789
790        let mut vectors = backend
791            .vector_index(
792                "articles",
793                "embedding",
794                2,
795                VectorIndexSpec::BruteForce,
796                VectorIndexOpenMode::Create,
797            )
798            .unwrap();
799        vectors.add(1, vec![1.0, 0.0]).unwrap();
800        vectors.add(2, vec![0.0, 1.0]).unwrap();
801        let hits = vectors.search_knn(&[1.0, 0.0], 1).unwrap();
802        assert_eq!(hits.entries()[0].doc_id, 1);
803    }
804
805    #[test]
806    fn sqlite_key_value_catalog_supports_existing_registry_contracts() {
807        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
808        let catalog = storage.catalog();
809        catalog.set_metadata("schema_version", "keyvalue").unwrap();
810        catalog.save_schema("public").unwrap();
811        catalog
812            .save_table(&TableSchema {
813                relation: uqa_storage::RelationIdentity::new("public", "docs"),
814                security: uqa_storage::RelationSecurityRow::legacy("uqa"),
815                object_id: [1; 16],
816                storage_generation: [1; 16],
817                analyzer_json: "{}".into(),
818                fts_fields: vec!["title".into()],
819                vector_fields: Vec::new(),
820                columns_json: "[]".into(),
821                constraints_json: String::new(),
822            })
823            .unwrap();
824        catalog
825            .save_analyzer("ko", "{\"name\":\"standard\"}")
826            .unwrap();
827        catalog
828            .save_table_field_analyzer("docs", "title", "index", "ko")
829            .unwrap();
830        catalog
831            .save_foreign_server("fs", "memory", "{\"root\":\"/tmp\"}")
832            .unwrap();
833        catalog
834            .save_catalog_index(
835                &uqa_storage::RelationIdentity::new("public", "idx_docs_title"),
836                "gin",
837                "public.docs",
838                "[\"title\"]",
839                "{}",
840            )
841            .unwrap();
842        catalog
843            .save_column_stats(ColumnStatsInput::basic(
844                "docs",
845                "title",
846                4,
847                0,
848                Some("a"),
849                Some("z"),
850                10,
851            ))
852            .unwrap();
853
854        assert_eq!(
855            catalog.get_metadata("schema_version").unwrap().as_deref(),
856            Some("keyvalue")
857        );
858        assert_eq!(
859            catalog.load_tables().unwrap()[0].relation.qualified_name(),
860            "public.docs"
861        );
862        assert_eq!(catalog.load_analyzers().unwrap()[0].0, "ko");
863        assert_eq!(catalog.load_foreign_servers().unwrap()[0].0, "fs");
864        assert_eq!(
865            catalog.load_catalog_indexes().unwrap()[0]
866                .relation
867                .qualified_name(),
868            "public.idx_docs_title"
869        );
870        assert_eq!(
871            catalog.load_column_stats("docs").unwrap()[0].distinct_count,
872            4
873        );
874    }
875}