uqa_storage_sqlite/connection/
native.rs1use uqa_storage::mvcc::{StorageMutationOrigin, VersionError, VersionedSessionOptions};
10use uqa_storage::read_control::StorageReadControl;
11use uqa_storage::KeyValueBatch;
12
13use super::logical::BoundRecordSession;
14use super::{Arc, KeyValueStore, ManagedConnection, Result, SQLiteError, VersionedKeyValueStore};
15use crate::mvcc::native::NativeSnapshot;
16
17impl ManagedConnection {
18 pub fn prune_diskann_changes(
20 &self,
21 source: &crate::vector_index::RetainedSQLiteDiskANNCanonical,
22 resolver: &dyn uqa_storage::diskann_index::catalog::DiskANNIndexResolver,
23 pruner: &uqa_storage::key_value::KeyValueDiskANNPruner,
24 request: uqa_storage::diskann_index::changes::DiskANNPruneRequest,
25 control: &StorageReadControl,
26 ) -> uqa_storage::StorageBackendResult<uqa_storage::diskann_index::changes::DiskANNPruneResult>
27 {
28 self.with_native_write(|snapshot, batch| {
29 Ok(source.prune_changes(resolver, pruner, (snapshot, batch), request, control)?)
30 })?
31 .ok_or_else(|| {
32 uqa_storage::StorageBackendError::Other(
33 "DiskANN pruning requires a bound native session".into(),
34 )
35 })
36 }
37
38 pub fn publish_diskann_generation(
40 &self,
41 coverage: &uqa_storage::diskann_index::build::DiskANNCanonicalCoverage<
42 crate::vector_index::RetainedSQLiteDiskANNCanonical,
43 >,
44 resolver: &dyn uqa_storage::diskann_index::catalog::DiskANNIndexResolver,
45 control: &StorageReadControl,
46 ) -> uqa_storage::StorageBackendResult<()> {
47 let sealed = self
48 .diskann_generations(control)?
49 .open_source(coverage.fingerprint().generation(), control)?;
50 self.with_native_write(|snapshot, batch| {
51 crate::vector_index::RetainedSQLiteDiskANNCanonical::publish_generation(
52 coverage, resolver, &sealed, snapshot, batch, control,
53 )?;
54 Ok(())
55 })?
56 .ok_or_else(|| {
57 uqa_storage::StorageBackendError::Other(
58 "DiskANN publication requires a bound native session".into(),
59 )
60 })
61 }
62
63 pub fn diskann_generations(
65 &self,
66 control: &StorageReadControl,
67 ) -> uqa_storage::StorageBackendResult<uqa_storage::key_value::KeyValueDiskANNStore> {
68 let records: Arc<dyn KeyValueStore> = Arc::new(self.native_diskann_records()?);
69 uqa_storage::key_value::KeyValueDiskANNStore::connect(&records, control)
70 }
71
72 pub(crate) fn native_diskann_records(&self) -> Result<crate::diskann::Records> {
73 self.surface_cleanup_failure()?;
74 let _gate = self.session.gate.read();
75 let logical = self
76 .session
77 .logical
78 .get()
79 .ok_or(SQLiteError::LogicalSessionRequired)?;
80 let namespace = logical.native.ok_or(SQLiteError::SessionMappingMismatch)?;
81 crate::diskann::Records::new(
82 logical.store.clone(),
83 namespace,
84 self.auxiliary_encryption_key(),
85 )
86 .map_err(Into::into)
87 }
88
89 pub(crate) fn native_identifier_watermark(&self, namespace: &[u8]) -> Result<Option<u64>> {
90 self.surface_cleanup_failure()?;
91 let _gate = self.session.gate.read();
92 let logical = self
93 .session
94 .logical
95 .get()
96 .filter(|session| session.native.is_some())
97 .ok_or(SQLiteError::SessionMappingMismatch)?;
98 logical.identifier_watermark(namespace).map_err(Into::into)
99 }
100
101 pub(crate) fn allocate_native_identifiers(
102 &self,
103 namespace: &[u8],
104 request: uqa_storage::mvcc::IdentifierRequest,
105 ) -> Result<uqa_storage::mvcc::IdentifierAllocation> {
106 self.surface_cleanup_failure()?;
107 let _gate = self.session.gate.read();
108 let logical = self
109 .session
110 .logical
111 .get()
112 .filter(|session| session.native.is_some())
113 .ok_or(SQLiteError::SessionMappingMismatch)?;
114 logical
115 .allocate_identifiers(namespace, request)
116 .map_err(Into::into)
117 }
118
119 pub(crate) fn is_native_record_session(&self) -> bool {
120 self.session
121 .logical
122 .get()
123 .is_some_and(|session| session.native.is_some())
124 }
125
126 pub fn bind_native_records(&self, options: VersionedSessionOptions) -> Result<()> {
128 self.surface_cleanup_failure()?;
129 let _gate = self.session.gate.write();
130 if let Some(logical) = self.session.logical.get() {
131 if logical.native.is_none() {
132 return Err(SQLiteError::SessionMappingMismatch);
133 }
134 return if logical.options().retained_bytes == options.retained_bytes {
135 Ok(())
136 } else {
137 Err(SQLiteError::SessionOptionsMismatch)
138 };
139 }
140 if self.session.transaction.lock().is_some() {
141 return Err(SQLiteError::TransactionAlreadyActive);
142 }
143 let identity = self.storage_identity()?;
144 let records = crate::SQLiteRecordStore::for_native(
145 &self.record_connection(),
146 &StorageReadControl::with_limit(options.retained_bytes),
147 )
148 .map_err(VersionError::into_storage_error)?;
149 let namespace = records
150 .native_namespace()
151 .ok_or(SQLiteError::SessionMappingMismatch)?;
152 self.session
153 .logical
154 .set(Arc::new(BoundRecordSession {
155 store: Arc::new(VersionedKeyValueStore::new_with_cancellation(
156 Arc::new(records),
157 identity,
158 options,
159 self.write_cancellation(),
160 )),
161 native: Some(namespace),
162 }))
163 .map_err(|_| SQLiteError::SessionMappingMismatch)
164 }
165
166 pub(crate) fn native_snapshot(&self) -> Result<Option<Arc<NativeSnapshot>>> {
167 self.surface_cleanup_failure()?;
168 let _gate = self.session.gate.read();
169 self.session
170 .logical
171 .get()
172 .map(|logical| {
173 NativeSnapshot::capture(
174 logical,
175 logical.native.ok_or(SQLiteError::SessionMappingMismatch)?,
176 )
177 .map(Arc::new)
178 })
179 .transpose()
180 }
181
182 pub(crate) fn with_native_write<R>(
183 &self,
184 operation: impl FnOnce(&NativeSnapshot, &mut dyn KeyValueBatch) -> Result<R>,
185 ) -> Result<Option<R>> {
186 self.surface_cleanup_failure()?;
187 let _gate = self.session.gate.write();
189 let Some(logical) = self.session.logical.get() else {
190 return Ok(None);
191 };
192 let database = logical.native.ok_or(SQLiteError::SessionMappingMismatch)?;
193 let own_transaction = !logical.in_transaction();
194 if own_transaction {
195 logical.begin_transaction()?;
196 }
197 let mut scope = WriteScope {
198 connection: self,
199 logical,
200 rollback: own_transaction,
201 };
202 let snapshot = NativeSnapshot::capture(logical, database)?;
203 let mut batch = logical.batch();
204 let result = operation(&snapshot, &mut *batch)?;
205 batch.commit()?;
206 scope.rollback = false;
208 if own_transaction {
209 logical.commit_transaction()?;
210 }
211 Ok(Some(result))
212 }
213
214 pub(crate) fn with_native_versioned_write<R>(
216 &self,
217 operation: impl FnOnce(
218 StorageMutationOrigin,
219 &NativeSnapshot,
220 &mut dyn KeyValueBatch,
221 ) -> Result<R>,
222 ) -> Result<R> {
223 self.surface_cleanup_failure()?;
224 let _gate = self.session.gate.write();
225 let logical = self
226 .session
227 .logical
228 .get()
229 .ok_or(SQLiteError::LogicalSessionRequired)?;
230 let database = logical.native.ok_or(SQLiteError::SessionMappingMismatch)?;
231 let control = logical.retention_control();
232 Ok(
233 logical.with_versioned_record_mutation(|origin, view, batch| {
234 operation(
235 origin,
236 &NativeSnapshot {
237 view,
238 control,
239 database,
240 history: origin.transaction().database(),
241 },
242 batch,
243 )
244 .map_err(Into::into)
245 })?,
246 )
247 }
248}
249
250struct WriteScope<'a> {
251 connection: &'a ManagedConnection,
252 logical: &'a BoundRecordSession,
253 rollback: bool,
254}
255
256impl Drop for WriteScope<'_> {
257 fn drop(&mut self) {
258 if self.rollback {
259 if let Err(error) = self.logical.rollback_transaction() {
260 *self.connection.session.cleanup_failure.lock() = Some(error.to_string());
261 }
262 }
263 }
264}
265
266#[cfg(test)]
267mod tests {
268 use super::*;
269
270 #[test]
271 fn native_evaluation_unwind_rolls_back_only_its_own_transaction() {
272 let connection = ManagedConnection::open_in_memory().unwrap();
273 crate::Catalog::open(connection.clone()).unwrap();
274 connection
275 .bind_native_records(VersionedSessionOptions::default())
276 .unwrap();
277 for explicit in [false, true] {
278 if explicit {
279 connection.begin_transaction().unwrap();
280 }
281 let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
282 let _: Result<Option<()>> = connection.with_native_write(|snapshot, batch| {
283 snapshot.ensure_table_owner("never-published", batch)?;
284 panic!("injected evaluation unwind");
285 });
286 }));
287 assert!(result.is_err());
288 assert_eq!(connection.in_transaction(), explicit);
289 assert!(connection
290 .native_snapshot()
291 .unwrap()
292 .unwrap()
293 .table_owner("never-published")
294 .unwrap()
295 .is_none());
296 if explicit {
297 connection.rollback_transaction().unwrap();
298 }
299 }
300 }
301
302 #[test]
303 fn native_document_writes_respect_a_read_only_logical_transaction() {
304 use uqa_storage::DocumentStore;
305 let connection = ManagedConnection::open_in_memory().unwrap();
306 crate::Catalog::open(connection.clone()).unwrap();
307 connection
308 .bind_native_records(VersionedSessionOptions::default())
309 .unwrap();
310 connection.begin_record_read().unwrap();
311 let mut documents = crate::SQLiteDocumentStore::new(connection.clone(), "docs");
312 assert!(documents.put(1, std::collections::BTreeMap::new()).is_err());
313 assert!(!connection.transaction_has_written().unwrap());
314 connection.commit_transaction().unwrap();
315 assert!(!documents.contains_doc_id(1).unwrap());
316 connection
317 .with_physical(|sqlite| {
318 assert_eq!(
319 sqlite.query_row("SELECT count(*) FROM _uqa_mvcc_identifiers", [], |row| {
320 row.get::<_, i64>(0)
321 })?,
322 0
323 );
324 Ok(())
325 })
326 .unwrap();
327 }
328
329 #[test]
330 fn native_autocommit_pins_preconditions_before_evaluating_mutation() {
331 use crate::mvcc::native::{NativeRecord, NativeRecordFamily};
332 use uqa_storage::DocumentStore;
333 let connection = ManagedConnection::open_in_memory().unwrap();
334 crate::Catalog::open(connection.clone()).unwrap();
335 connection
336 .bind_native_records(VersionedSessionOptions::default())
337 .unwrap();
338 let mut a = crate::SQLiteDocumentStore::new(connection.clone(), "docs");
339 let fields = |n| std::collections::BTreeMap::from([("n".into(), uqa_core::Value::Int(n))]);
340 a.put(1, fields(1)).unwrap();
341 let mut b = crate::SQLiteDocumentStore::new(connection.new_session(), "docs");
342 let result = connection.with_native_write(|snapshot, batch| {
343 let owner = snapshot.table_owner("docs")?.unwrap();
344 let old = snapshot
345 .read_row(
346 NativeRecordFamily::Documents,
347 owner,
348 &[rusqlite::types::ValueRef::Integer(1)],
349 |row| {
350 Ok(NativeRecord::encode(
351 NativeRecordFamily::Documents,
352 owner,
353 row,
354 &snapshot.control,
355 )?)
356 },
357 )?
358 .unwrap();
359 b.put(1, fields(2))?;
361 batch.put(old.key(), old.row())?;
362 Ok(())
363 });
364 assert!(result.is_err());
365 connection.rollback_transaction().unwrap();
366 assert_eq!(a.get(1).unwrap(), Some(fields(2)));
367 }
368}