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