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