Skip to main content

uqa_storage/
catalog.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Backend-neutral persistent catalog facade.
8//!
9//! The engine depends on this trait for table metadata, analyzers, models,
10//! graph registries, and planner statistics. Concrete storage layers such as
11//! `SQLite` or a future RocksDB-backed catalog implement it behind the same
12//! object-safe boundary.
13
14use serde::{Deserialize, Serialize};
15
16use crate::backend::{StorageBackendError, StorageBackendResult};
17
18mod cache_revisions;
19mod graph_access;
20pub mod graph_guards;
21pub mod graph_identifiers;
22pub mod graph_observations;
23pub(crate) mod graph_snapshot;
24mod identity;
25mod record_revisions;
26mod relation;
27pub mod relation_acl;
28mod relation_security;
29mod schema;
30mod sequence_security;
31mod sequence_values;
32
33pub use cache_revisions::CatalogCacheRevisions;
34pub use graph_access::validate_graph_page;
35pub use graph_access::{
36    GraphEntityFilter, GraphEntityKind, GraphEntitySelector, MAX_GRAPH_ID_PAGE,
37};
38pub use identity::new_nonzero_catalog_identity;
39pub use record_revisions::{CatalogRecordRef, CatalogRecordRevision};
40pub use relation::RelationIdentity;
41pub use relation_security::{BoundRelationSecurity, LegacyRelationSecurity, RelationSecurityRow};
42pub use sequence_security::{BoundSequenceSecurity, LegacySequenceSecurity, SequenceSecurityRow};
43pub use sequence_values::{
44    sequence_value_allocation, sequence_value_reservation, SequenceLogResult,
45    SequenceReservationResult, SequenceSetValueResult, SequenceValueAllocation,
46    SequenceValuePosition, SequenceValueReservation,
47};
48mod table;
49
50pub use schema::{BoundSchemaRow, SchemaAclEntry, SchemaPrivileges, SchemaRow};
51pub use table::{TableAclEntry, TablePrivileges};
52
53/// A borrowed metadata record on one catalog read boundary. Callbacks must not reenter persistence.
54pub type MetadataReadVisitor<'a> = dyn FnMut(&str, &str) -> StorageBackendResult<()> + 'a;
55
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
57#[serde(rename_all = "snake_case")]
58pub enum RelationKind {
59    Table,
60    View,
61    Sequence,
62    ForeignTable,
63    Index,
64}
65
66impl RelationKind {
67    pub fn as_str(self) -> &'static str {
68        match self {
69            Self::Table => "table",
70            Self::View => "view",
71            Self::Sequence => "sequence",
72            Self::ForeignTable => "foreign_table",
73            Self::Index => "index",
74        }
75    }
76}
77
78#[derive(Debug, Clone, Serialize, Deserialize)]
79pub struct TableSchema {
80    pub relation: RelationIdentity,
81    #[serde(flatten)]
82    pub security: RelationSecurityRow,
83    /// Stable logical relation identity. `CREATE TABLE` allocates a new value, while renames, schema changes, `TRUNCATE`, and reopen preserve it. A zero value marks a legacy catalog row that the engine upgrades during open.
84    #[serde(default)]
85    pub object_id: [u8; 16],
86    /// Stable physical-storage identity. `CREATE TABLE` and `TRUNCATE` allocate a new value, while schema-only alterations and renames preserve it. A zero value marks a legacy catalog row that the engine upgrades during open.
87    #[serde(default)]
88    pub storage_generation: [u8; 16],
89    pub analyzer_json: String,
90    pub fts_fields: Vec<String>,
91    pub vector_fields: Vec<VectorFieldSchema>,
92    /// Serialized `Vec<uqa_sql::ast::ColumnDef>` capturing the schema
93    /// columns (name, type, `auto_increment`, flags). Empty for
94    /// tables created by the legacy code path before column tracking
95    /// existed.
96    #[serde(default)]
97    pub columns_json: String,
98    /// Serialized `uqa_sql::ast::TableConstraintSet`. Empty for catalogs
99    /// created before durable table constraints were introduced.
100    #[serde(default)]
101    pub constraints_json: String,
102}
103
104#[derive(Debug, Clone, Serialize, Deserialize)]
105pub struct VectorFieldSchema {
106    pub field: String,
107    pub dimensions: u32,
108}
109
110/// One row from graph-edge persistence, represented as a typed struct so the
111/// catalog API stays explicit and clippy-clean.
112#[derive(Debug, Clone)]
113pub struct EdgeRow {
114    pub edge_id: u64,
115    pub source_id: u64,
116    pub target_id: u64,
117    pub label: String,
118    pub properties_json: String,
119}
120
121/// One vertex in an atomic named-graph snapshot replacement.
122#[derive(Debug, Clone)]
123pub struct GraphVertexRow {
124    pub vertex_id: u64,
125    pub label: String,
126    pub properties_json: String,
127}
128
129/// Complete persisted shape of one named graph. Catalog implementations
130/// replace the graph membership and entity rows as one atomic operation.
131#[derive(Debug, Clone)]
132pub struct GraphSnapshot {
133    pub vertices: Vec<GraphVertexRow>,
134    pub edges: Vec<EdgeRow>,
135    pub label_registry_json: String,
136}
137
138/// One row from the foreign-table registry.
139#[derive(Debug, Clone)]
140pub struct ForeignTableRow {
141    pub relation: RelationIdentity,
142    pub security: RelationSecurityRow,
143    pub server_name: String,
144    pub columns_json: String,
145    pub options_json: String,
146}
147
148/// One foreign-server definition. Execution owns the versioned SQL metadata; absence identifies a legacy row.
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct ForeignServerRow {
151    pub name: String,
152    pub fdw_type: String,
153    pub options_json: String,
154    pub metadata_json: Option<String>,
155}
156
157/// One durable view definition. `definition_json` contains a serialized
158/// planner query plan, while ownership remains a typed catalog relation.
159#[derive(Debug, Clone)]
160pub struct ViewRow {
161    pub relation: RelationIdentity,
162    pub security: RelationSecurityRow,
163    pub definition_json: String,
164}
165
166pub use uqa_core::catalog_index::CatalogIndexRow;
167
168/// Values persisted into one column-statistics row.
169#[derive(Debug, Clone, Copy)]
170pub struct ColumnStatsInput<'a> {
171    pub table_name: &'a str,
172    pub column_name: &'a str,
173    pub distinct_count: i64,
174    pub null_count: i64,
175    pub min_value: Option<&'a str>,
176    pub max_value: Option<&'a str>,
177    pub row_count: i64,
178    pub histogram_json: &'a str,
179    pub mcv_values_json: &'a str,
180    pub mcv_frequencies_json: &'a str,
181}
182
183impl<'a> ColumnStatsInput<'a> {
184    pub fn basic(
185        table_name: &'a str,
186        column_name: &'a str,
187        distinct_count: i64,
188        null_count: i64,
189        min_value: Option<&'a str>,
190        max_value: Option<&'a str>,
191        row_count: i64,
192    ) -> Self {
193        Self {
194            table_name,
195            column_name,
196            distinct_count,
197            null_count,
198            min_value,
199            max_value,
200            row_count,
201            histogram_json: "[]",
202            mcv_values_json: "[]",
203            mcv_frequencies_json: "[]",
204        }
205    }
206}
207
208/// One row from persisted column statistics.
209#[derive(Debug, Clone, PartialEq)]
210pub struct ColumnStatsRow {
211    pub column_name: String,
212    pub distinct_count: i64,
213    pub null_count: i64,
214    pub min_value: Option<String>,
215    pub max_value: Option<String>,
216    pub row_count: i64,
217    pub histogram_json: String,
218    pub mcv_values_json: String,
219    pub mcv_frequencies_json: String,
220}
221
222/// Durable SQL sequence state. Sequence allocation is implemented by the
223/// catalog backend as one atomic mutation so independent engine sessions (and
224/// independently opened engines) cannot return the same value.
225#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
226pub struct SequenceOptions {
227    pub data_type: String,
228    /// `None` is accepted only while decoding a legacy row and is resolved from its increment direction by native sequence restoration.
229    pub min_value: Option<i64>,
230    /// `None` is accepted only while decoding a legacy row and is resolved from its increment direction by native sequence restoration.
231    pub max_value: Option<i64>,
232    pub cycle: bool,
233    #[serde(default = "default_sequence_cache_size")]
234    pub cache_size: i64,
235}
236
237const fn default_sequence_cache_size() -> i64 {
238    1
239}
240
241impl Default for SequenceOptions {
242    fn default() -> Self {
243        Self {
244            data_type: "bigint".into(),
245            min_value: None,
246            max_value: None,
247            cycle: false,
248            cache_size: default_sequence_cache_size(),
249        }
250    }
251}
252
253pub use uqa_core::catalog_sequence::{
254    SequenceAclEntry, SequenceOwner, SequenceOwnerDependency, SequencePrivileges,
255};
256
257#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
258pub struct SequenceRow {
259    pub relation: RelationIdentity,
260    /// Captured owner and ACL role identities, or a legacy row awaiting initial-open migration.
261    #[serde(flatten)]
262    pub security: SequenceSecurityRow,
263    /// Stable identity of this sequence incarnation. Dropping and recreating the same qualified name must allocate a different value.
264    #[serde(default)]
265    pub object_id: [u8; 16],
266    /// Changes when value-generation options or persistence replace the sequence's allocation state. Stable across ownership and name changes, value reservations, and `setval`.
267    #[serde(default)]
268    pub definition_generation: [u8; 16],
269    pub start: i64,
270    pub increment: i64,
271    pub current: i64,
272    /// False until the first allocation returns `current` verbatim.
273    pub called: bool,
274    /// Number of values whose advancement is already durable in the sequence log.
275    #[serde(default)]
276    pub log_count: i64,
277    /// `PostgreSQL` `pg_class.relpersistence` code. Durable sequence rows accept only permanent (`p`) and unlogged (`u`) values.
278    pub persistence: String,
279    #[serde(default)]
280    pub owner: Option<SequenceOwner>,
281    #[serde(default)]
282    pub options: SequenceOptions,
283}
284
285/// Engine-facing catalog facade for persistent metadata.
286pub trait CatalogFacade: Send + Sync {
287    /// Transaction model and database incarnation shared with the paired backend. Wrappers must forward this with the session affinity.
288    fn transaction_model(&self) -> crate::StorageTransactionModel {
289        crate::StorageTransactionModel::ProviderSerialized
290    }
291
292    /// Identity shared with the paired data backend's transaction context. Wrappers must delegate this when their underlying catalog reports an identity.
293    fn transaction_affinity(&self) -> Option<crate::StorageSessionAffinity> {
294        None
295    }
296
297    /// Prepare durable catalog storage inside the backend's owning initial-restore transaction. Already initialized catalogs may keep the default.
298    fn initialize_storage(&self) -> StorageBackendResult<()> {
299        Ok(())
300    }
301
302    /// Read transactional cache generations without loading schemas or column
303    /// statistics. Providers without change tracking use conservative reloads.
304    fn cache_revisions(&self) -> StorageBackendResult<Option<CatalogCacheRevisions>> {
305        Ok(None)
306    }
307
308    /// Read selected catalog-record identities from one committed/private boundary, in request order and without loading table data. An outer `None` means this provider has no exact record tracking; an inner `None` means the selected record is absent. Callers must not interpret unavailable tracking as an unchanged object.
309    fn record_revisions(
310        &self,
311        _records: &[CatalogRecordRef<'_>],
312    ) -> StorageBackendResult<Option<Vec<Option<CatalogRecordRevision>>>> {
313        Ok(None)
314    }
315
316    /// Native producers admit selected revision buffers before allocation. External catalogs retain their existing snapshot operation and lend its immutable revision identities into an admitted destination.
317    fn record_revisions_with_control(
318        &self,
319        records: &[CatalogRecordRef<'_>],
320        control: &uqa_core::memory::ProductionControl<'_>,
321    ) -> StorageBackendResult<Option<uqa_core::memory::Produced<Vec<Option<CatalogRecordRevision>>>>>
322    {
323        control.check()?;
324        let Some(revisions) = self.record_revisions(records)? else {
325            return Ok(None);
326        };
327        let mut output = uqa_core::memory::ProductionVec::new(*control);
328        output.reserve(revisions.len())?;
329        for revision in revisions {
330            output.push_produced(control.finish(revision, control.empty_reservation())?)?;
331        }
332        Ok(Some(output.finish()?))
333    }
334
335    fn set_metadata(&self, key: &str, value: &str) -> StorageBackendResult<()>;
336    /// Remove one metadata record, retaining its private deletion and write precondition until transaction end.
337    fn delete_metadata(&self, key: &str) -> StorageBackendResult<()>;
338    fn get_metadata(&self, key: &str) -> StorageBackendResult<Option<String>>;
339    /// Visit matching metadata records on one catalog snapshot without collecting their payloads. The prefix is literal, including NUL and wildcard characters. Providers retain their original read allowance and cancellation; an error stops the scan before the next record. The callback must not reenter persistence and owns any retained output. Unsupported providers must reject this operation instead of materializing all records.
340    fn visit_metadata_with_prefix(
341        &self,
342        _prefix: &str,
343        _visit: &mut MetadataReadVisitor<'_>,
344    ) -> StorageBackendResult<()> {
345        Err(StorageBackendError::Other(
346            "borrowed metadata reads are not supported by this catalog".into(),
347        ))
348    }
349    /// Visit a literal metadata prefix whose complete keys have the supplied UTF-8 byte length. Preserve the same borrowed read boundary and error contract as `visit_metadata_with_prefix`. Length-prefixed providers can seek the encoded length and prefix together instead of scanning unrelated metadata families. Unsupported providers must reject the operation.
350    fn visit_metadata_with_key_length(
351        &self,
352        _prefix: &str,
353        _key_bytes: usize,
354        _visit: &mut MetadataReadVisitor<'_>,
355    ) -> StorageBackendResult<()> {
356        Err(StorageBackendError::Other(
357            "fixed-length metadata reads are not supported by this catalog".into(),
358        ))
359    }
360    /// Collect matching metadata records from one catalog snapshot; output allocation belongs to the caller. The prefix is literal, including NUL and wildcard characters.
361    fn metadata_with_prefix(&self, prefix: &str) -> StorageBackendResult<Vec<(String, String)>> {
362        let mut entries = Vec::new();
363        self.visit_metadata_with_prefix(prefix, &mut |key, value| {
364            entries.push((key.to_owned(), value.to_owned()));
365            Ok(())
366        })?;
367        Ok(entries)
368    }
369    /// Replace one already bound relation or attribute ACL without rewriting its definition. The caller holds the relation lifetime and catalog tuple locks until transaction end.
370    fn save_relation_acl(
371        &self,
372        relation: &RelationIdentity,
373        column: Option<&str>,
374        entry: &relation_acl::RelationAclTuple,
375    ) -> StorageBackendResult<()> {
376        if !self.transaction_model().is_versioned() {
377            return relation_acl::save_serialized(self, relation, column, entry);
378        }
379        self.set_metadata(&relation_acl::key(relation, column), &entry.encode(column)?)
380    }
381    /// Whether this metadata key has a transaction-private replacement in the current session.
382    fn metadata_has_private_changes(&self, _key: &str) -> StorageBackendResult<bool> {
383        if self.transaction_model().is_versioned() {
384            return Err(StorageBackendError::Other(
385                "private metadata provenance is not supported by this catalog".into(),
386            ));
387        }
388        Ok(false)
389    }
390    /// Persist evaluated maintenance state. Concurrent providers merge its counters under their existing record-publication boundary; serialized providers use an ordinary metadata replacement.
391    fn save_statistics_maintenance(
392        &self,
393        table: &str,
394        state: &crate::statistics_maintenance::StatisticsMaintenance,
395    ) -> StorageBackendResult<()> {
396        self.set_metadata(
397            &crate::statistics_maintenance::StatisticsMaintenance::key(table),
398            &serde_json::to_string(state)?,
399        )
400    }
401    fn fts_storage_was_reset(&self) -> bool {
402        false
403    }
404
405    /// Atomically migrate the former flat relation namespace into typed,
406    /// schema-owned catalog objects. Implementations must reject normalized
407    /// or cross-kind collisions instead of merging either object.
408    fn migrate_relation_namespace(&self) -> StorageBackendResult<()>;
409
410    fn save_schema_row(&self, schema: &SchemaRow) -> StorageBackendResult<()>;
411    fn drop_schema(&self, name: &str) -> StorageBackendResult<()>;
412    fn load_schema_rows(&self) -> StorageBackendResult<Vec<SchemaRow>>;
413
414    /// Whether this exact schema has a private creation, replacement or deletion in the current session.
415    fn schema_has_private_changes(&self, _name: &str) -> StorageBackendResult<bool> {
416        if self.transaction_model().is_versioned() {
417            return Err(StorageBackendError::Other(
418                "private schema provenance is not supported by this catalog".into(),
419            ));
420        }
421        Ok(false)
422    }
423
424    fn save_schema(&self, name: &str) -> StorageBackendResult<()> {
425        self.save_schema_row(&SchemaRow::bootstrap(name))
426    }
427
428    fn load_schemas(&self) -> StorageBackendResult<Vec<String>> {
429        Ok(self
430            .load_schema_rows()?
431            .into_iter()
432            .map(|schema| schema.name().to_owned())
433            .collect())
434    }
435
436    fn save_table(&self, schema: &TableSchema) -> StorageBackendResult<()>;
437    fn load_tables(&self) -> StorageBackendResult<Vec<TableSchema>>;
438    fn drop_table(&self, name: &str) -> StorageBackendResult<()>;
439    /// Remove a table definition and every catalog/data row owned by it as
440    /// one atomic catalog operation.
441    fn drop_table_and_data(&self, name: &str) -> StorageBackendResult<()>;
442    fn purge_table_data(&self, name: &str) -> StorageBackendResult<()>;
443    fn rename_table_data(&self, from: &str, to: &str) -> StorageBackendResult<()>;
444    fn drop_column_data(&self, table_name: &str, column_name: &str) -> StorageBackendResult<()>;
445    fn rename_column_data(
446        &self,
447        table_name: &str,
448        from: &str,
449        to: &str,
450    ) -> StorageBackendResult<()>;
451
452    fn save_model(&self, name: &str, json: &str) -> StorageBackendResult<()>;
453    fn load_models(&self) -> StorageBackendResult<Vec<(String, String)>>;
454    fn load_model(&self, name: &str) -> StorageBackendResult<Option<String>>;
455    fn drop_model(&self, name: &str) -> StorageBackendResult<()>;
456
457    fn save_scoring_params(&self, name: &str, params_json: &str) -> StorageBackendResult<()>;
458    fn load_scoring_params(&self, name: &str) -> StorageBackendResult<Option<String>>;
459    fn load_all_scoring_params(&self) -> StorageBackendResult<Vec<(String, String)>>;
460    fn drop_scoring_params(&self, name: &str) -> StorageBackendResult<()>;
461
462    /// Create a sequence's definition and the value record of its definition generation, which starts at the value state of `sequence`.
463    fn create_sequence_row(&self, sequence: &SequenceRow) -> StorageBackendResult<bool>;
464    /// Replace a sequence's definition, ownership and security. A row that keeps its object identity and definition generation leaves the generation's value record, which only value operations move; a row with a new generation replaces the old generation's value record with one that starts at the value state of `sequence`.
465    fn replace_sequence_row(&self, sequence: &SequenceRow) -> StorageBackendResult<bool>;
466    /// Atomically move one sequence catalog row and its shared relation claim while preserving object identity and the generation's value record.
467    fn rename_sequence_row(&self, from: &str, to: &str) -> StorageBackendResult<bool>;
468    /// Remove a sequence's definition together with the value record of its generation.
469    fn drop_sequence_row(&self, name: &str) -> StorageBackendResult<bool>;
470    /// Sequence definitions, each with the value state of its generation's value record.
471    fn load_sequence_rows(&self) -> StorageBackendResult<Vec<SequenceRow>>;
472
473    /// Whether this sequence's definition has transaction-private changes, including creation, rename, deletion and definition replacement, which the transaction's own catalog reads must select.
474    fn sequence_has_private_changes(
475        &self,
476        _relation: &RelationIdentity,
477        _object_id: [u8; 16],
478    ) -> StorageBackendResult<bool> {
479        if self.transaction_model().is_versioned() {
480            return Err(StorageBackendError::Other(
481                "private sequence provenance is not supported by this catalog".into(),
482            ));
483        }
484        Ok(false)
485    }
486
487    /// Whether the value record of this definition generation has transaction-private changes, which holds exactly when the current transaction created the generation. Values of such a generation are allocated in the transaction, since no other session can see it; the value record of a committed generation is moved only outside any transaction, as `PostgreSQL` moves a sequence's state whatever happens to the transaction that drew from it.
488    fn sequence_value_has_private_changes(
489        &self,
490        _object_id: [u8; 16],
491        _definition_generation: [u8; 16],
492    ) -> StorageBackendResult<bool> {
493        if self.transaction_model().is_versioned() {
494            return Err(StorageBackendError::Other(
495                "private sequence value provenance is not supported by this catalog".into(),
496            ));
497        }
498        Ok(false)
499    }
500
501    /// Move the value state that earlier releases kept in sequence definitions into value records. Only an initial open runs this, inside its catalog preparation.
502    fn migrate_sequence_values(&self) -> StorageBackendResult<()> {
503        Ok(())
504    }
505    /// Reserve the next block of values from the value record of this generation of `object_id`, whatever name the sequence currently has. `DefinitionChanged` reports that another generation of the sequence has replaced this one, and `Missing` that the sequence no longer exists.
506    fn reserve_sequence_values(
507        &self,
508        name: &str,
509        object_id: [u8; 16],
510        definition_generation: [u8; 16],
511    ) -> StorageBackendResult<SequenceReservationResult>;
512    /// Compatibility allocation API for callers that do not retain a session cache. A cached reservation's unused values are intentionally abandoned, just as when a `PostgreSQL` session disconnects.
513    fn next_sequence_value(
514        &self,
515        name: &str,
516        object_id: [u8; 16],
517    ) -> StorageBackendResult<Option<i64>> {
518        loop {
519            let relation =
520                RelationIdentity::from_legacy_name(name).map_err(StorageBackendError::Other)?;
521            let Some(row) = self
522                .load_sequence_rows()?
523                .into_iter()
524                .find(|row| row.relation == relation && row.object_id == object_id)
525            else {
526                return Ok(None);
527            };
528            match self.reserve_sequence_values(name, object_id, row.definition_generation)? {
529                SequenceReservationResult::Reserved(reservation) => {
530                    return Ok(Some(reservation.first_value));
531                }
532                SequenceReservationResult::DefinitionChanged => {}
533                SequenceReservationResult::Missing => return Ok(None),
534                SequenceReservationResult::Exhausted => {
535                    return Err(StorageBackendError::Other(format!(
536                        "sequence `{name}` exhausted"
537                    )));
538                }
539            }
540        }
541    }
542    /// Replace the value state in the value record of this generation of `object_id`, with the results `reserve_sequence_values` reports.
543    fn set_sequence_value(
544        &self,
545        name: &str,
546        object_id: [u8; 16],
547        definition_generation: [u8; 16],
548        value: i64,
549        called: bool,
550        log_count: i64,
551    ) -> StorageBackendResult<SequenceSetValueResult>;
552    /// Move the durable position in the value record of this generation of `object_id` to `logged` when its value and called flag still are `expected`. Nothing is written otherwise, and `Changed` reports the position the record holds. A caller that hands out values at or below a logged value records that value here before it hands any of them out.
553    fn log_sequence_values(
554        &self,
555        name: &str,
556        object_id: [u8; 16],
557        definition_generation: [u8; 16],
558        expected: (i64, bool),
559        logged: SequenceValuePosition,
560    ) -> StorageBackendResult<SequenceLogResult>;
561
562    fn save_view(&self, view: &ViewRow) -> StorageBackendResult<()>;
563    /// Atomically move one view catalog row and its shared relation claim.
564    fn rename_view(
565        &self,
566        from: &RelationIdentity,
567        to: &RelationIdentity,
568    ) -> StorageBackendResult<bool>;
569    fn drop_view(&self, relation: &RelationIdentity) -> StorageBackendResult<bool>;
570    fn load_views(&self) -> StorageBackendResult<Vec<ViewRow>>;
571
572    /// Whether this exact view record has a private creation, replacement or deletion in the current session, including either end of a rename.
573    fn view_has_private_changes(&self, _relation: &RelationIdentity) -> StorageBackendResult<bool> {
574        if self.transaction_model().is_versioned() {
575            return Err(StorageBackendError::Other(
576                "private view provenance is not supported by this catalog".into(),
577            ));
578        }
579        Ok(false)
580    }
581
582    fn save_named_graph(&self, name: &str) -> StorageBackendResult<()>;
583    /// Bind graph mutations to their definition and allocation generation while allowing independent data writers to share the definition. Concurrent backends and catalog wrappers must implement this capability.
584    fn guard_graph_definition(&self, _graph: Option<&str>) -> StorageBackendResult<()> {
585        Err(crate::StorageBackendError::Other(
586            "graph definition guards are not supported".into(),
587        ))
588    }
589    fn drop_named_graph(&self, name: &str) -> StorageBackendResult<()>;
590    fn load_named_graphs(&self) -> StorageBackendResult<Vec<String>>;
591    fn named_graph_exists(&self, name: &str) -> StorageBackendResult<bool>;
592
593    /// Read one entity without loading any other graph payload.
594    fn graph_vertex(&self, id: u64) -> StorageBackendResult<Option<GraphVertexRow>>;
595
596    /// Visit requested vertices on the pinned view, including missing rows and
597    /// duplicates in caller order. The internal callback must not reenter
598    /// storage. A false result stops before the next identity is admitted.
599    /// `None` declines the capability without invoking the callback; `Some`
600    /// counts all invocations, including the one that stopped the read.
601    fn for_each_graph_vertex_borrowed(
602        &self,
603        _ids: &[u64],
604        _visit: &mut dyn FnMut(u64, Option<&GraphVertexRow>) -> bool,
605    ) -> StorageBackendResult<Option<usize>> {
606        Ok(None)
607    }
608
609    fn graph_edge(&self, id: u64) -> StorageBackendResult<Option<EdgeRow>>;
610
611    /// Read a bounded, strictly ascending identity page from the pinned
612    /// storage snapshot. Filters must be applied before the page limit.
613    fn graph_entity_ids(
614        &self,
615        filter: GraphEntityFilter<'_>,
616        after: Option<u64>,
617        limit: usize,
618    ) -> StorageBackendResult<Vec<u64>>;
619
620    fn graph_entity_count(&self, filter: GraphEntityFilter<'_>) -> StorageBackendResult<u64>;
621    fn graph_entity_max_id(&self, kind: GraphEntityKind) -> StorageBackendResult<Option<u64>>;
622    fn graph_entity_memberships(
623        &self,
624        kind: GraphEntityKind,
625        id: u64,
626    ) -> StorageBackendResult<Vec<String>>;
627    fn graph_has_membership(
628        &self,
629        kind: GraphEntityKind,
630        id: u64,
631        graph: &str,
632    ) -> StorageBackendResult<bool>;
633    /// Explicit bulk snapshot/export of one named graph. The caller pins
634    /// the storage transaction. Engine startup, sessions, and query handles
635    /// use direct access methods instead of retaining this owned copy.
636    fn load_named_graph_snapshot(&self, name: &str) -> StorageBackendResult<Option<GraphSnapshot>> {
637        graph_snapshot::load(self, name)
638    }
639    fn save_vertex(
640        &self,
641        vertex_id: u64,
642        label: &str,
643        properties_json: &str,
644    ) -> StorageBackendResult<()>;
645    fn delete_vertex(&self, vertex_id: u64) -> StorageBackendResult<()>;
646    fn load_vertices(&self) -> StorageBackendResult<Vec<(u64, String, String)>>;
647    fn save_edge(
648        &self,
649        edge_id: u64,
650        source_id: u64,
651        target_id: u64,
652        label: &str,
653        properties_json: &str,
654    ) -> StorageBackendResult<()>;
655    fn delete_edge(&self, edge_id: u64) -> StorageBackendResult<()>;
656    fn load_edges(&self) -> StorageBackendResult<Vec<EdgeRow>>;
657    fn save_graph_membership(
658        &self,
659        entity_type: &str,
660        entity_id: u64,
661        graph_name: &str,
662    ) -> StorageBackendResult<()>;
663    fn delete_graph_membership(
664        &self,
665        entity_type: &str,
666        entity_id: u64,
667        graph_name: &str,
668    ) -> StorageBackendResult<()>;
669    fn delete_graph_membership_for_graph(&self, graph_name: &str) -> StorageBackendResult<()>;
670    fn load_graph_memberships(&self) -> StorageBackendResult<Vec<(String, u64, String)>>;
671    fn purge_orphan_graph_entities(&self) -> StorageBackendResult<()>;
672    fn replace_named_graph(
673        &self,
674        graph_name: &str,
675        snapshot: &GraphSnapshot,
676    ) -> StorageBackendResult<()>;
677    fn drop_named_graph_data(&self, graph_name: &str) -> StorageBackendResult<()>;
678
679    fn save_analyzer(&self, name: &str, config_json: &str) -> StorageBackendResult<()>;
680    fn drop_analyzer(&self, name: &str) -> StorageBackendResult<()>;
681    fn load_analyzers(&self) -> StorageBackendResult<Vec<(String, String)>>;
682
683    /// Save a named definition's resolved descriptor with its diagnostic configuration in the same transaction.
684    fn save_analyzer_revision(
685        &self,
686        _name: &str,
687        _config_json: &str,
688        _descriptor_json: &str,
689    ) -> StorageBackendResult<()> {
690        Err(StorageBackendError::Other(
691            "durable analyzer descriptors are not supported by this catalog".into(),
692        ))
693    }
694
695    /// Resolved named descriptors; legacy definitions appear only in `load_analyzers` until migrated.
696    fn load_analyzer_descriptors(&self) -> StorageBackendResult<Vec<(String, String)>> {
697        Ok(Vec::new())
698    }
699
700    /// Atomically replace a field's complete independent binding and its compatibility label. An empty label denotes the physical field's unnamed default.
701    fn replace_table_field_analyzer_binding(
702        &self,
703        _table: &str,
704        _field: &str,
705        _phase: &str,
706        _name: &str,
707        _binding_json: &str,
708    ) -> StorageBackendResult<()> {
709        Err(StorageBackendError::Other(
710            "durable analyzer bindings are not supported by this catalog".into(),
711        ))
712    }
713
714    /// `(table, field, binding JSON)` rows. Each field has one complete binding envelope.
715    fn load_table_field_analyzer_bindings(
716        &self,
717    ) -> StorageBackendResult<Vec<(String, String, String)>> {
718        Ok(Vec::new())
719    }
720
721    fn save_table_field_analyzer(
722        &self,
723        table_name: &str,
724        field: &str,
725        phase: &str,
726        analyzer_name: &str,
727    ) -> StorageBackendResult<()>;
728    fn replace_table_field_analyzer(
729        &self,
730        table_name: &str,
731        field: &str,
732        phase: &str,
733        analyzer_name: &str,
734    ) -> StorageBackendResult<()>;
735    fn drop_table_field_analyzer_field(
736        &self,
737        table_name: &str,
738        field: &str,
739    ) -> StorageBackendResult<()>;
740    fn drop_table_field_analyzers(&self, table_name: &str) -> StorageBackendResult<()>;
741    fn load_table_field_analyzers(
742        &self,
743    ) -> StorageBackendResult<Vec<(String, String, String, String)>>;
744
745    fn save_foreign_server(
746        &self,
747        name: &str,
748        fdw_type: &str,
749        options_json: &str,
750    ) -> StorageBackendResult<()>;
751    fn drop_foreign_server(&self, name: &str) -> StorageBackendResult<()>;
752    fn load_foreign_servers(&self) -> StorageBackendResult<Vec<(String, String, String)>>;
753
754    /// Atomically replace a complete foreign-server row. A catalog without metadata support must reject it instead of discarding the metadata.
755    fn save_foreign_server_row(&self, row: &ForeignServerRow) -> StorageBackendResult<()> {
756        if row.metadata_json.is_some() {
757            return Err(StorageBackendError::Other(
758                "foreign-server metadata is not supported by this catalog".into(),
759            ));
760        }
761        self.save_foreign_server(&row.name, &row.fdw_type, &row.options_json)
762    }
763
764    /// Read definitions and their metadata from one catalog view. Legacy implementations expose absent metadata explicitly.
765    fn load_foreign_server_rows(&self) -> StorageBackendResult<Vec<ForeignServerRow>> {
766        Ok(self
767            .load_foreign_servers()?
768            .into_iter()
769            .map(|(name, fdw_type, options_json)| ForeignServerRow {
770                name,
771                fdw_type,
772                options_json,
773                metadata_json: None,
774            })
775            .collect())
776    }
777
778    fn save_foreign_table(&self, row: &ForeignTableRow) -> StorageBackendResult<()>;
779    /// Atomically move one foreign-table catalog row and its shared relation claim.
780    fn rename_foreign_table(
781        &self,
782        from: &RelationIdentity,
783        to: &RelationIdentity,
784    ) -> StorageBackendResult<bool>;
785    fn update_foreign_table_security(
786        &self,
787        relation: &RelationIdentity,
788        security: &RelationSecurityRow,
789    ) -> StorageBackendResult<bool>;
790    fn drop_foreign_table(&self, relation: &RelationIdentity) -> StorageBackendResult<()>;
791    fn load_foreign_tables(&self) -> StorageBackendResult<Vec<ForeignTableRow>>;
792
793    /// Whether this exact foreign-table record has a private creation, replacement or deletion in the current session, including either end of a rename.
794    fn foreign_table_has_private_changes(
795        &self,
796        _relation: &RelationIdentity,
797    ) -> StorageBackendResult<bool> {
798        if self.transaction_model().is_versioned() {
799            return Err(StorageBackendError::Other(
800                "private foreign-table provenance is not supported by this catalog".into(),
801            ));
802        }
803        Ok(false)
804    }
805
806    fn save_catalog_index(
807        &self,
808        relation: &RelationIdentity,
809        index_type: &str,
810        table_name: &str,
811        columns_json: &str,
812        parameters_json: &str,
813    ) -> StorageBackendResult<()> {
814        self.save_catalog_index_row(&CatalogIndexRow {
815            relation: relation.clone(),
816            index_type: index_type.to_string(),
817            table_name: table_name.to_string(),
818            columns_json: columns_json.to_string(),
819            parameters_json: parameters_json.to_string(),
820            definition_json: None,
821        })
822    }
823    fn save_catalog_index_row(&self, index: &CatalogIndexRow) -> StorageBackendResult<()>;
824    fn drop_catalog_index(&self, relation: &RelationIdentity) -> StorageBackendResult<()>;
825    fn drop_catalog_indexes_for_table(&self, table_name: &str) -> StorageBackendResult<()>;
826    fn load_catalog_indexes(&self) -> StorageBackendResult<Vec<CatalogIndexRow>>;
827
828    fn save_path_index(
829        &self,
830        graph_name: &str,
831        label_sequences_json: &str,
832    ) -> StorageBackendResult<()>;
833    fn drop_path_index(&self, graph_name: &str) -> StorageBackendResult<()>;
834    fn load_path_indexes(&self) -> StorageBackendResult<Vec<(String, String)>>;
835
836    /// Durable reachability records, paged lexicographically by (source, target).
837    /// Building calls clear, bounded saves, then finish inside one transaction.
838    /// Graph mutations invalidate the materialization atomically; definitions remain.
839    fn clear_path_index_data(&self, index: &str) -> StorageBackendResult<()>;
840    fn save_path_index_pairs(
841        &self,
842        index: &str,
843        sequence: &str,
844        pairs: &[(u64, u64)],
845    ) -> StorageBackendResult<()>;
846    fn finish_path_index_data(
847        &self,
848        index: &str,
849        graph: &str,
850        definition: &str,
851    ) -> StorageBackendResult<()>;
852    fn path_index_data_is_current(
853        &self,
854        index: &str,
855        definition: &str,
856    ) -> StorageBackendResult<bool>;
857    fn path_index_pairs(
858        &self,
859        index: &str,
860        sequence: &str,
861        after: Option<(u64, u64)>,
862        limit: usize,
863    ) -> StorageBackendResult<Vec<(u64, u64)>>;
864
865    fn save_column_stats(&self, stats: ColumnStatsInput<'_>) -> StorageBackendResult<()>;
866    /// Atomically replace the complete statistics snapshot for one table.
867    /// Implementations must leave the prior snapshot intact if any row fails.
868    fn replace_column_stats(
869        &self,
870        table_name: &str,
871        stats: &[ColumnStatsInput<'_>],
872    ) -> StorageBackendResult<()>;
873    fn load_column_stats(&self, table_name: &str) -> StorageBackendResult<Vec<ColumnStatsRow>>;
874    fn delete_column_stats(&self, table_name: &str) -> StorageBackendResult<()>;
875}
876
877#[cfg(test)]
878mod tests {
879    use super::RelationIdentity;
880
881    #[test]
882    fn relation_identity_rendering_is_reversible_and_collision_free() {
883        let left = RelationIdentity::new("a.b", "c");
884        let right = RelationIdentity::new("a", "b.c");
885        assert_eq!(left.qualified_name(), "\"a.b\".c");
886        assert_eq!(right.qualified_name(), "a.\"b.c\"");
887        assert_ne!(left.qualified_name(), right.qualified_name());
888        assert_eq!(
889            RelationIdentity::from_legacy_name(&left.qualified_name()).unwrap(),
890            left
891        );
892        assert_eq!(
893            RelationIdentity::from_legacy_name(&right.qualified_name()).unwrap(),
894            right
895        );
896    }
897
898    #[test]
899    fn relation_identity_preserves_quotes_and_unqualified_public_alias() {
900        let quoted = RelationIdentity::new("public", "a\"b.c");
901        assert_eq!(quoted.qualified_name(), "public.\"a\"\"b.c\"");
902        assert_eq!(
903            quoted.canonical_and_legacy_public_names(),
904            vec![
905                "public.\"a\"\"b.c\"".to_string(),
906                "\"a\"\"b.c\"".to_string()
907            ]
908        );
909        assert_eq!(
910            RelationIdentity::from_legacy_name(&quoted.qualified_name()).unwrap(),
911            quoted
912        );
913        assert_eq!(
914            RelationIdentity::from_legacy_name("plain").unwrap(),
915            RelationIdentity::new("public", "plain")
916        );
917        assert_eq!(
918            RelationIdentity::new("app", "plain").canonical_and_legacy_public_names(),
919            vec!["app.plain".to_string()]
920        );
921        assert_eq!(
922            RelationIdentity::new("public", "Upper").canonical_and_legacy_public_names(),
923            vec![
924                "public.\"Upper\"".to_string(),
925                "\"Upper\"".to_string(),
926                "Upper".to_string()
927            ]
928        );
929    }
930}