Skip to main content

uqa_storage_sqlite/connection/
native.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Native row operations share one logical session, including the read boundary of each evaluated mutation.
8
9use uqa_storage::mvcc::{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(crate) fn native_identifier_watermark(&self, namespace: &[u8]) -> Result<Option<u64>> {
19        self.surface_cleanup_failure()?;
20        let _gate = self.session.gate.read();
21        let logical = self
22            .session
23            .logical
24            .get()
25            .filter(|session| session.native.is_some())
26            .ok_or(SQLiteError::SessionMappingMismatch)?;
27        logical.identifier_watermark(namespace).map_err(Into::into)
28    }
29
30    pub(crate) fn allocate_native_identifiers(
31        &self,
32        namespace: &[u8],
33        request: uqa_storage::mvcc::IdentifierRequest,
34    ) -> Result<uqa_storage::mvcc::IdentifierAllocation> {
35        self.surface_cleanup_failure()?;
36        let _gate = self.session.gate.read();
37        let logical = self
38            .session
39            .logical
40            .get()
41            .filter(|session| session.native.is_some())
42            .ok_or(SQLiteError::SessionMappingMismatch)?;
43        logical
44            .allocate_identifiers(namespace, request)
45            .map_err(Into::into)
46    }
47
48    pub(crate) fn is_native_record_session(&self) -> bool {
49        self.session
50            .logical
51            .get()
52            .is_some_and(|session| session.native.is_some())
53    }
54
55    /// Bind a new or existing native catalog or recognized standalone graph file to shared logical record transactions, initializing/upgrading and converting its physical format atomically if needed. Document/B-tree stores, exact/IVF/HNSW vectors, occurrences and catalog operations share this session. Native provider factories publish a legacy catalog restore and its baseline together before attaching this session; direct callers must bind before opening a catalog on an already converted file. Standalone graph handles retain their scoped records, including handles opened before binding. Direct physical access is rejected.
56    pub fn bind_native_records(&self, options: VersionedSessionOptions) -> Result<()> {
57        self.surface_cleanup_failure()?;
58        let _gate = self.session.gate.write();
59        if let Some(logical) = self.session.logical.get() {
60            if logical.native.is_none() {
61                return Err(SQLiteError::SessionMappingMismatch);
62            }
63            return if logical.options().retained_bytes == options.retained_bytes {
64                Ok(())
65            } else {
66                Err(SQLiteError::SessionOptionsMismatch)
67            };
68        }
69        if self.session.transaction.lock().is_some() {
70            return Err(SQLiteError::TransactionAlreadyActive);
71        }
72        let identity = self.storage_identity()?;
73        let records = crate::SQLiteRecordStore::for_native(
74            &self.record_connection(),
75            &StorageReadControl::with_limit(options.retained_bytes),
76        )
77        .map_err(VersionError::into_storage_error)?;
78        let namespace = records
79            .native_namespace()
80            .ok_or(SQLiteError::SessionMappingMismatch)?;
81        self.session
82            .logical
83            .set(Arc::new(BoundRecordSession {
84                store: Arc::new(VersionedKeyValueStore::new_with_cancellation(
85                    Arc::new(records),
86                    identity,
87                    options,
88                    self.write_cancellation(),
89                )),
90                native: Some(namespace),
91            }))
92            .map_err(|_| SQLiteError::SessionMappingMismatch)
93    }
94
95    pub(crate) fn native_snapshot(&self) -> Result<Option<Arc<NativeSnapshot>>> {
96        self.surface_cleanup_failure()?;
97        let _gate = self.session.gate.read();
98        self.session
99            .logical
100            .get()
101            .map(|logical| {
102                NativeSnapshot::capture(
103                    logical,
104                    logical.native.ok_or(SQLiteError::SessionMappingMismatch)?,
105                )
106                .map(Arc::new)
107            })
108            .transpose()
109    }
110
111    pub(crate) fn with_native_write<R>(
112        &self,
113        operation: impl FnOnce(&NativeSnapshot, &mut dyn KeyValueBatch) -> Result<R>,
114    ) -> Result<Option<R>> {
115        self.surface_cleanup_failure()?;
116        // This gate covers read/evaluate/stage, not just each individual byte-store call.
117        let _gate = self.session.gate.write();
118        let Some(logical) = self.session.logical.get() else {
119            return Ok(None);
120        };
121        let database = logical.native.ok_or(SQLiteError::SessionMappingMismatch)?;
122        let own_transaction = !logical.in_transaction();
123        if own_transaction {
124            logical.begin_transaction()?;
125        }
126        let mut scope = WriteScope {
127            connection: self,
128            logical,
129            rollback: own_transaction,
130        };
131        let snapshot = NativeSnapshot::capture(logical, database)?;
132        let mut batch = logical.batch();
133        let result = operation(&snapshot, &mut *batch)?;
134        batch.commit()?;
135        // A failed publication keeps its evaluated attempt for explicit receipt resolution.
136        scope.rollback = false;
137        if own_transaction {
138            logical.commit_transaction()?;
139        }
140        Ok(Some(result))
141    }
142}
143
144struct WriteScope<'a> {
145    connection: &'a ManagedConnection,
146    logical: &'a BoundRecordSession,
147    rollback: bool,
148}
149
150impl Drop for WriteScope<'_> {
151    fn drop(&mut self) {
152        if self.rollback {
153            if let Err(error) = self.logical.rollback_transaction() {
154                *self.connection.session.cleanup_failure.lock() = Some(error.to_string());
155            }
156        }
157    }
158}
159
160#[cfg(test)]
161mod tests {
162    use super::*;
163
164    #[test]
165    fn native_evaluation_unwind_rolls_back_only_its_own_transaction() {
166        let connection = ManagedConnection::open_in_memory().unwrap();
167        crate::Catalog::open(connection.clone()).unwrap();
168        connection
169            .bind_native_records(VersionedSessionOptions::default())
170            .unwrap();
171        for explicit in [false, true] {
172            if explicit {
173                connection.begin_transaction().unwrap();
174            }
175            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
176                let _: Result<Option<()>> = connection.with_native_write(|snapshot, batch| {
177                    snapshot.ensure_table_owner("never-published", batch)?;
178                    panic!("injected evaluation unwind");
179                });
180            }));
181            assert!(result.is_err());
182            assert_eq!(connection.in_transaction(), explicit);
183            assert!(connection
184                .native_snapshot()
185                .unwrap()
186                .unwrap()
187                .table_owner("never-published")
188                .unwrap()
189                .is_none());
190            if explicit {
191                connection.rollback_transaction().unwrap();
192            }
193        }
194    }
195
196    #[test]
197    fn native_document_writes_respect_a_read_only_logical_transaction() {
198        use uqa_storage::DocumentStore;
199        let connection = ManagedConnection::open_in_memory().unwrap();
200        crate::Catalog::open(connection.clone()).unwrap();
201        connection
202            .bind_native_records(VersionedSessionOptions::default())
203            .unwrap();
204        connection.begin_record_read().unwrap();
205        let mut documents = crate::SQLiteDocumentStore::new(connection.clone(), "docs");
206        assert!(documents.put(1, std::collections::BTreeMap::new()).is_err());
207        assert!(!connection.transaction_has_written().unwrap());
208        connection.commit_transaction().unwrap();
209        assert!(!documents.contains_doc_id(1).unwrap());
210        connection
211            .with_physical(|sqlite| {
212                assert_eq!(
213                    sqlite.query_row("SELECT count(*) FROM _uqa_mvcc_identifiers", [], |row| {
214                        row.get::<_, i64>(0)
215                    })?,
216                    0
217                );
218                Ok(())
219            })
220            .unwrap();
221    }
222
223    #[test]
224    fn native_autocommit_pins_preconditions_before_evaluating_mutation() {
225        use crate::mvcc::native::{NativeRecord, NativeRecordFamily};
226        use uqa_storage::DocumentStore;
227        let connection = ManagedConnection::open_in_memory().unwrap();
228        crate::Catalog::open(connection.clone()).unwrap();
229        connection
230            .bind_native_records(VersionedSessionOptions::default())
231            .unwrap();
232        let mut a = crate::SQLiteDocumentStore::new(connection.clone(), "docs");
233        let fields = |n| std::collections::BTreeMap::from([("n".into(), uqa_core::Value::Int(n))]);
234        a.put(1, fields(1)).unwrap();
235        let mut b = crate::SQLiteDocumentStore::new(connection.new_session(), "docs");
236        let result = connection.with_native_write(|snapshot, batch| {
237            let owner = snapshot.table_owner("docs")?.unwrap();
238            let old = snapshot
239                .read_row(
240                    NativeRecordFamily::Documents,
241                    owner,
242                    &[rusqlite::types::ValueRef::Integer(1)],
243                    |row| {
244                        Ok(NativeRecord::encode(
245                            NativeRecordFamily::Documents,
246                            owner,
247                            row,
248                            &snapshot.control,
249                        )?)
250                    },
251                )?
252                .unwrap();
253            // B publishes after A's evaluation read but before A stages its result.
254            b.put(1, fields(2))?;
255            batch.put(old.key(), old.row())?;
256            Ok(())
257        });
258        assert!(result.is_err());
259        connection.rollback_transaction().unwrap();
260        assert_eq!(a.get(1).unwrap(), Some(fields(2)));
261    }
262}