Skip to main content

uqa_graph/persistent_store/
storage.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical graph access shared by engine catalogs and standalone `SQLite`.
8
9use uqa_core::{Edge, Vertex};
10use uqa_storage::{GraphEntityFilter, GraphEntityKind};
11
12use crate::{GraphLabelRegistry, GraphStoreResult};
13
14pub use super::identifiers::{decode_identifier_generation, GraphIdentifierScope};
15
16/// Open a write transaction or a nested savepoint on the exact storage session.
17pub fn begin_graph_write(
18    backend: std::sync::Arc<dyn uqa_storage::PersistentStorageBackend>,
19) -> GraphStoreResult<Box<dyn GraphWriteTransaction>> {
20    let savepoint = if backend.in_transaction() {
21        let id = uqa_storage::StorageSavepointId::allocate();
22        backend.savepoint(id)?;
23        Some(id)
24    } else {
25        backend.begin_transaction()?;
26        None
27    };
28    Ok(Box::new(StorageGraphWriteTransaction {
29        backend,
30        savepoint,
31        active: true,
32    }))
33}
34
35struct StorageGraphWriteTransaction {
36    backend: std::sync::Arc<dyn uqa_storage::PersistentStorageBackend>,
37    savepoint: Option<uqa_storage::StorageSavepointId>,
38    active: bool,
39}
40
41impl GraphWriteTransaction for StorageGraphWriteTransaction {
42    fn commit(&mut self) -> GraphStoreResult<()> {
43        if let Some(id) = self.savepoint {
44            self.backend.release_savepoint(id)?;
45        } else {
46            self.backend.commit_transaction()?;
47        }
48        self.active = false;
49        Ok(())
50    }
51
52    fn rollback(&mut self) -> GraphStoreResult<()> {
53        if !self.active {
54            return Ok(());
55        }
56        if let Some(id) = self.savepoint {
57            self.backend.rollback_to_savepoint(id)?;
58            self.backend.release_savepoint(id)?;
59        } else {
60            self.backend.rollback_transaction()?;
61        }
62        self.active = false;
63        Ok(())
64    }
65}
66
67impl Drop for StorageGraphWriteTransaction {
68    fn drop(&mut self) {
69        if self.active {
70            let _ = self.rollback();
71        }
72    }
73}
74
75/// A live storage checkpoint. Implementations also roll back on Drop so a
76/// panic cannot publish half a graph mutation.
77pub trait GraphWriteTransaction {
78    fn commit(&mut self) -> GraphStoreResult<()>;
79    fn rollback(&mut self) -> GraphStoreResult<()>;
80}
81
82/// No entity, membership, or adjacency collection is retained by a handle.
83/// Multi-read operations run in the caller's pinned storage transaction.
84pub trait GraphStorage: Send + Sync {
85    /// A selection can combine an original snapshot with private entities from another clear generation. Visit each physical namespace supplying that view without observing provider validation reads.
86    fn visit_selection_namespaces(
87        &self,
88        visit: &mut dyn FnMut(
89            uqa_storage::catalog::graph_identifiers::GraphIdentifierNamespace,
90        ) -> GraphStoreResult<()>,
91    ) -> GraphStoreResult<()> {
92        let namespace = self.identifiers()?.ok_or_else(|| {
93            crate::GraphStoreError::Storage(
94                "serializable graph selections require an immutable namespace".into(),
95            )
96        })?;
97        visit(namespace.namespace())
98    }
99    /// Select the same physical identity generation as the entity read. An overlay may read untouched entities from its original snapshot and changed entities from its writer.
100    fn entity_observation_namespace(
101        &self,
102        _kind: GraphEntityKind,
103        _id: u64,
104    ) -> GraphStoreResult<Option<uqa_storage::catalog::graph_identifiers::GraphIdentifierNamespace>>
105    {
106        Ok(self.identifiers()?.map(|scope| scope.namespace()))
107    }
108    /// Autonomous identifiers for this physical entity namespace and its current clear generation. Missing capability retains serialized counter updates.
109    fn identifiers(&self) -> GraphStoreResult<Option<GraphIdentifierScope<'_>>> {
110        Ok(None)
111    }
112    fn guard_definition(&self, _graph: Option<&str>) -> GraphStoreResult<()> {
113        if self.identifiers()?.is_some() {
114            return Err(crate::GraphStoreError::Storage(
115                "graph definition guards are not supported".into(),
116            ));
117        }
118        Ok(())
119    }
120    /// Select a fresh durable namespace when clearing every graph and entity. Providers exposing identifiers must implement this transactionally.
121    fn reset_identifiers(&self) -> GraphStoreResult<()> {
122        if self.identifiers()?.is_some() {
123            return Err(crate::GraphStoreError::Storage(
124                "graph storage cannot reset its identifier generation".into(),
125            ));
126        }
127        Ok(())
128    }
129    /// Copy only transaction-local write identities when preparing a new
130    /// command candidate. The underlying durable snapshots remain shared.
131    fn fork_overlay(&self) -> Option<std::sync::Arc<dyn GraphStorage>> {
132        None
133    }
134    fn unmodified_read_snapshot(&self) -> Option<super::PersistentGraphStore> {
135        None
136    }
137    fn begin_write(&self) -> GraphStoreResult<Box<dyn GraphWriteTransaction>>;
138    fn graph_names(&self) -> GraphStoreResult<Vec<String>>;
139    fn has_graph(&self, graph: &str) -> GraphStoreResult<bool>;
140    fn create_graph(&self, graph: &str) -> GraphStoreResult<()>;
141    fn delete_graph(&self, graph: &str) -> GraphStoreResult<()>;
142    fn registry(&self, graph: &str) -> GraphStoreResult<GraphLabelRegistry>;
143    fn save_registry(&self, graph: &str, registry: &GraphLabelRegistry) -> GraphStoreResult<()>;
144    fn counter(&self, kind: GraphEntityKind) -> GraphStoreResult<Option<u64>>;
145    fn save_counter(&self, kind: GraphEntityKind, next: u64) -> GraphStoreResult<()>;
146    fn vertex(&self, id: u64) -> GraphStoreResult<Option<Vertex>>;
147    fn edge(&self, id: u64) -> GraphStoreResult<Option<Edge>>;
148    fn save_vertex(&self, vertex: &Vertex) -> GraphStoreResult<()>;
149    fn save_edge(&self, edge: &Edge) -> GraphStoreResult<()>;
150    fn delete_vertex(&self, id: u64) -> GraphStoreResult<()>;
151    fn delete_edge(&self, id: u64) -> GraphStoreResult<()>;
152    fn ids(
153        &self,
154        filter: GraphEntityFilter<'_>,
155        after: Option<u64>,
156        limit: usize,
157    ) -> GraphStoreResult<Vec<u64>>;
158    fn count(&self, filter: GraphEntityFilter<'_>) -> GraphStoreResult<u64>;
159    fn max_id(&self, kind: GraphEntityKind) -> GraphStoreResult<Option<u64>>;
160    fn memberships(&self, kind: GraphEntityKind, id: u64) -> GraphStoreResult<Vec<String>>;
161    fn has_membership(&self, kind: GraphEntityKind, id: u64, graph: &str)
162        -> GraphStoreResult<bool>;
163    fn attach(&self, kind: GraphEntityKind, id: u64, graph: &str) -> GraphStoreResult<()>;
164    fn detach(&self, kind: GraphEntityKind, id: u64, graph: &str) -> GraphStoreResult<()>;
165}