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    fn set_metadata(&self, key: &str, value: &str) -> StorageBackendResult<()>;
317    /// Remove one metadata record, retaining its private deletion and write precondition until transaction end.
318    fn delete_metadata(&self, key: &str) -> StorageBackendResult<()>;
319    fn get_metadata(&self, key: &str) -> StorageBackendResult<Option<String>>;
320    /// 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.
321    fn visit_metadata_with_prefix(
322        &self,
323        _prefix: &str,
324        _visit: &mut MetadataReadVisitor<'_>,
325    ) -> StorageBackendResult<()> {
326        Err(StorageBackendError::Other(
327            "borrowed metadata reads are not supported by this catalog".into(),
328        ))
329    }
330    /// 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.
331    fn visit_metadata_with_key_length(
332        &self,
333        _prefix: &str,
334        _key_bytes: usize,
335        _visit: &mut MetadataReadVisitor<'_>,
336    ) -> StorageBackendResult<()> {
337        Err(StorageBackendError::Other(
338            "fixed-length metadata reads are not supported by this catalog".into(),
339        ))
340    }
341    /// Collect matching metadata records from one catalog snapshot; output allocation belongs to the caller. The prefix is literal, including NUL and wildcard characters.
342    fn metadata_with_prefix(&self, prefix: &str) -> StorageBackendResult<Vec<(String, String)>> {
343        let mut entries = Vec::new();
344        self.visit_metadata_with_prefix(prefix, &mut |key, value| {
345            entries.push((key.to_owned(), value.to_owned()));
346            Ok(())
347        })?;
348        Ok(entries)
349    }
350    /// 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.
351    fn save_relation_acl(
352        &self,
353        relation: &RelationIdentity,
354        column: Option<&str>,
355        entry: &relation_acl::RelationAclTuple,
356    ) -> StorageBackendResult<()> {
357        if !self.transaction_model().is_versioned() {
358            return relation_acl::save_serialized(self, relation, column, entry);
359        }
360        self.set_metadata(&relation_acl::key(relation, column), &entry.encode(column)?)
361    }
362    /// Whether this metadata key has a transaction-private replacement in the current session.
363    fn metadata_has_private_changes(&self, _key: &str) -> StorageBackendResult<bool> {
364        if self.transaction_model().is_versioned() {
365            return Err(StorageBackendError::Other(
366                "private metadata provenance is not supported by this catalog".into(),
367            ));
368        }
369        Ok(false)
370    }
371    /// Persist evaluated maintenance state. Concurrent providers merge its counters under their existing record-publication boundary; serialized providers use an ordinary metadata replacement.
372    fn save_statistics_maintenance(
373        &self,
374        table: &str,
375        state: &crate::statistics_maintenance::StatisticsMaintenance,
376    ) -> StorageBackendResult<()> {
377        self.set_metadata(
378            &crate::statistics_maintenance::StatisticsMaintenance::key(table),
379            &serde_json::to_string(state)?,
380        )
381    }
382    fn fts_storage_was_reset(&self) -> bool {
383        false
384    }
385
386    /// Atomically migrate the former flat relation namespace into typed,
387    /// schema-owned catalog objects. Implementations must reject normalized
388    /// or cross-kind collisions instead of merging either object.
389    fn migrate_relation_namespace(&self) -> StorageBackendResult<()>;
390
391    fn save_schema_row(&self, schema: &SchemaRow) -> StorageBackendResult<()>;
392    fn drop_schema(&self, name: &str) -> StorageBackendResult<()>;
393    fn load_schema_rows(&self) -> StorageBackendResult<Vec<SchemaRow>>;
394
395    /// Whether this exact schema has a private creation, replacement or deletion in the current session.
396    fn schema_has_private_changes(&self, _name: &str) -> StorageBackendResult<bool> {
397        if self.transaction_model().is_versioned() {
398            return Err(StorageBackendError::Other(
399                "private schema provenance is not supported by this catalog".into(),
400            ));
401        }
402        Ok(false)
403    }
404
405    fn save_schema(&self, name: &str) -> StorageBackendResult<()> {
406        self.save_schema_row(&SchemaRow::bootstrap(name))
407    }
408
409    fn load_schemas(&self) -> StorageBackendResult<Vec<String>> {
410        Ok(self
411            .load_schema_rows()?
412            .into_iter()
413            .map(|schema| schema.name().to_owned())
414            .collect())
415    }
416
417    fn save_table(&self, schema: &TableSchema) -> StorageBackendResult<()>;
418    fn load_tables(&self) -> StorageBackendResult<Vec<TableSchema>>;
419    fn drop_table(&self, name: &str) -> StorageBackendResult<()>;
420    /// Remove a table definition and every catalog/data row owned by it as
421    /// one atomic catalog operation.
422    fn drop_table_and_data(&self, name: &str) -> StorageBackendResult<()>;
423    fn purge_table_data(&self, name: &str) -> StorageBackendResult<()>;
424    fn rename_table_data(&self, from: &str, to: &str) -> StorageBackendResult<()>;
425    fn drop_column_data(&self, table_name: &str, column_name: &str) -> StorageBackendResult<()>;
426    fn rename_column_data(
427        &self,
428        table_name: &str,
429        from: &str,
430        to: &str,
431    ) -> StorageBackendResult<()>;
432
433    fn save_model(&self, name: &str, json: &str) -> StorageBackendResult<()>;
434    fn load_models(&self) -> StorageBackendResult<Vec<(String, String)>>;
435    fn load_model(&self, name: &str) -> StorageBackendResult<Option<String>>;
436    fn drop_model(&self, name: &str) -> StorageBackendResult<()>;
437
438    fn save_scoring_params(&self, name: &str, params_json: &str) -> StorageBackendResult<()>;
439    fn load_scoring_params(&self, name: &str) -> StorageBackendResult<Option<String>>;
440    fn load_all_scoring_params(&self) -> StorageBackendResult<Vec<(String, String)>>;
441    fn drop_scoring_params(&self, name: &str) -> StorageBackendResult<()>;
442
443    /// Create a sequence's definition and the value record of its definition generation, which starts at the value state of `sequence`.
444    fn create_sequence_row(&self, sequence: &SequenceRow) -> StorageBackendResult<bool>;
445    /// 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`.
446    fn replace_sequence_row(&self, sequence: &SequenceRow) -> StorageBackendResult<bool>;
447    /// Atomically move one sequence catalog row and its shared relation claim while preserving object identity and the generation's value record.
448    fn rename_sequence_row(&self, from: &str, to: &str) -> StorageBackendResult<bool>;
449    /// Remove a sequence's definition together with the value record of its generation.
450    fn drop_sequence_row(&self, name: &str) -> StorageBackendResult<bool>;
451    /// Sequence definitions, each with the value state of its generation's value record.
452    fn load_sequence_rows(&self) -> StorageBackendResult<Vec<SequenceRow>>;
453
454    /// 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.
455    fn sequence_has_private_changes(
456        &self,
457        _relation: &RelationIdentity,
458        _object_id: [u8; 16],
459    ) -> StorageBackendResult<bool> {
460        if self.transaction_model().is_versioned() {
461            return Err(StorageBackendError::Other(
462                "private sequence provenance is not supported by this catalog".into(),
463            ));
464        }
465        Ok(false)
466    }
467
468    /// 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.
469    fn sequence_value_has_private_changes(
470        &self,
471        _object_id: [u8; 16],
472        _definition_generation: [u8; 16],
473    ) -> StorageBackendResult<bool> {
474        if self.transaction_model().is_versioned() {
475            return Err(StorageBackendError::Other(
476                "private sequence value provenance is not supported by this catalog".into(),
477            ));
478        }
479        Ok(false)
480    }
481
482    /// Move the value state that earlier releases kept in sequence definitions into value records. Only an initial open runs this, inside its catalog preparation.
483    fn migrate_sequence_values(&self) -> StorageBackendResult<()> {
484        Ok(())
485    }
486    /// 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.
487    fn reserve_sequence_values(
488        &self,
489        name: &str,
490        object_id: [u8; 16],
491        definition_generation: [u8; 16],
492    ) -> StorageBackendResult<SequenceReservationResult>;
493    /// 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.
494    fn next_sequence_value(
495        &self,
496        name: &str,
497        object_id: [u8; 16],
498    ) -> StorageBackendResult<Option<i64>> {
499        loop {
500            let relation =
501                RelationIdentity::from_legacy_name(name).map_err(StorageBackendError::Other)?;
502            let Some(row) = self
503                .load_sequence_rows()?
504                .into_iter()
505                .find(|row| row.relation == relation && row.object_id == object_id)
506            else {
507                return Ok(None);
508            };
509            match self.reserve_sequence_values(name, object_id, row.definition_generation)? {
510                SequenceReservationResult::Reserved(reservation) => {
511                    return Ok(Some(reservation.first_value));
512                }
513                SequenceReservationResult::DefinitionChanged => {}
514                SequenceReservationResult::Missing => return Ok(None),
515                SequenceReservationResult::Exhausted => {
516                    return Err(StorageBackendError::Other(format!(
517                        "sequence `{name}` exhausted"
518                    )));
519                }
520            }
521        }
522    }
523    /// Replace the value state in the value record of this generation of `object_id`, with the results `reserve_sequence_values` reports.
524    fn set_sequence_value(
525        &self,
526        name: &str,
527        object_id: [u8; 16],
528        definition_generation: [u8; 16],
529        value: i64,
530        called: bool,
531        log_count: i64,
532    ) -> StorageBackendResult<SequenceSetValueResult>;
533    /// 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.
534    fn log_sequence_values(
535        &self,
536        name: &str,
537        object_id: [u8; 16],
538        definition_generation: [u8; 16],
539        expected: (i64, bool),
540        logged: SequenceValuePosition,
541    ) -> StorageBackendResult<SequenceLogResult>;
542
543    fn save_view(&self, view: &ViewRow) -> StorageBackendResult<()>;
544    /// Atomically move one view catalog row and its shared relation claim.
545    fn rename_view(
546        &self,
547        from: &RelationIdentity,
548        to: &RelationIdentity,
549    ) -> StorageBackendResult<bool>;
550    fn drop_view(&self, relation: &RelationIdentity) -> StorageBackendResult<bool>;
551    fn load_views(&self) -> StorageBackendResult<Vec<ViewRow>>;
552
553    /// Whether this exact view record has a private creation, replacement or deletion in the current session, including either end of a rename.
554    fn view_has_private_changes(&self, _relation: &RelationIdentity) -> StorageBackendResult<bool> {
555        if self.transaction_model().is_versioned() {
556            return Err(StorageBackendError::Other(
557                "private view provenance is not supported by this catalog".into(),
558            ));
559        }
560        Ok(false)
561    }
562
563    fn save_named_graph(&self, name: &str) -> StorageBackendResult<()>;
564    /// 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.
565    fn guard_graph_definition(&self, _graph: Option<&str>) -> StorageBackendResult<()> {
566        Err(crate::StorageBackendError::Other(
567            "graph definition guards are not supported".into(),
568        ))
569    }
570    fn drop_named_graph(&self, name: &str) -> StorageBackendResult<()>;
571    fn load_named_graphs(&self) -> StorageBackendResult<Vec<String>>;
572    fn named_graph_exists(&self, name: &str) -> StorageBackendResult<bool>;
573
574    /// Read one entity without loading any other graph payload.
575    fn graph_vertex(&self, id: u64) -> StorageBackendResult<Option<GraphVertexRow>>;
576
577    /// Visit requested vertices on the pinned view, including missing rows and
578    /// duplicates in caller order. The internal callback must not reenter
579    /// storage. A false result stops before the next identity is admitted.
580    /// `None` declines the capability without invoking the callback; `Some`
581    /// counts all invocations, including the one that stopped the read.
582    fn for_each_graph_vertex_borrowed(
583        &self,
584        _ids: &[u64],
585        _visit: &mut dyn FnMut(u64, Option<&GraphVertexRow>) -> bool,
586    ) -> StorageBackendResult<Option<usize>> {
587        Ok(None)
588    }
589
590    fn graph_edge(&self, id: u64) -> StorageBackendResult<Option<EdgeRow>>;
591
592    /// Read a bounded, strictly ascending identity page from the pinned
593    /// storage snapshot. Filters must be applied before the page limit.
594    fn graph_entity_ids(
595        &self,
596        filter: GraphEntityFilter<'_>,
597        after: Option<u64>,
598        limit: usize,
599    ) -> StorageBackendResult<Vec<u64>>;
600
601    fn graph_entity_count(&self, filter: GraphEntityFilter<'_>) -> StorageBackendResult<u64>;
602    fn graph_entity_max_id(&self, kind: GraphEntityKind) -> StorageBackendResult<Option<u64>>;
603    fn graph_entity_memberships(
604        &self,
605        kind: GraphEntityKind,
606        id: u64,
607    ) -> StorageBackendResult<Vec<String>>;
608    fn graph_has_membership(
609        &self,
610        kind: GraphEntityKind,
611        id: u64,
612        graph: &str,
613    ) -> StorageBackendResult<bool>;
614    /// Explicit bulk snapshot/export of one named graph. The caller pins
615    /// the storage transaction. Engine startup, sessions, and query handles
616    /// use direct access methods instead of retaining this owned copy.
617    fn load_named_graph_snapshot(&self, name: &str) -> StorageBackendResult<Option<GraphSnapshot>> {
618        graph_snapshot::load(self, name)
619    }
620    fn save_vertex(
621        &self,
622        vertex_id: u64,
623        label: &str,
624        properties_json: &str,
625    ) -> StorageBackendResult<()>;
626    fn delete_vertex(&self, vertex_id: u64) -> StorageBackendResult<()>;
627    fn load_vertices(&self) -> StorageBackendResult<Vec<(u64, String, String)>>;
628    fn save_edge(
629        &self,
630        edge_id: u64,
631        source_id: u64,
632        target_id: u64,
633        label: &str,
634        properties_json: &str,
635    ) -> StorageBackendResult<()>;
636    fn delete_edge(&self, edge_id: u64) -> StorageBackendResult<()>;
637    fn load_edges(&self) -> StorageBackendResult<Vec<EdgeRow>>;
638    fn save_graph_membership(
639        &self,
640        entity_type: &str,
641        entity_id: u64,
642        graph_name: &str,
643    ) -> StorageBackendResult<()>;
644    fn delete_graph_membership(
645        &self,
646        entity_type: &str,
647        entity_id: u64,
648        graph_name: &str,
649    ) -> StorageBackendResult<()>;
650    fn delete_graph_membership_for_graph(&self, graph_name: &str) -> StorageBackendResult<()>;
651    fn load_graph_memberships(&self) -> StorageBackendResult<Vec<(String, u64, String)>>;
652    fn purge_orphan_graph_entities(&self) -> StorageBackendResult<()>;
653    fn replace_named_graph(
654        &self,
655        graph_name: &str,
656        snapshot: &GraphSnapshot,
657    ) -> StorageBackendResult<()>;
658    fn drop_named_graph_data(&self, graph_name: &str) -> StorageBackendResult<()>;
659
660    fn save_analyzer(&self, name: &str, config_json: &str) -> StorageBackendResult<()>;
661    fn drop_analyzer(&self, name: &str) -> StorageBackendResult<()>;
662    fn load_analyzers(&self) -> StorageBackendResult<Vec<(String, String)>>;
663
664    /// Save a named definition's resolved descriptor with its diagnostic configuration in the same transaction.
665    fn save_analyzer_revision(
666        &self,
667        _name: &str,
668        _config_json: &str,
669        _descriptor_json: &str,
670    ) -> StorageBackendResult<()> {
671        Err(StorageBackendError::Other(
672            "durable analyzer descriptors are not supported by this catalog".into(),
673        ))
674    }
675
676    /// Resolved named descriptors; legacy definitions appear only in `load_analyzers` until migrated.
677    fn load_analyzer_descriptors(&self) -> StorageBackendResult<Vec<(String, String)>> {
678        Ok(Vec::new())
679    }
680
681    /// Atomically replace a field's complete independent binding and its compatibility label. An empty label denotes the physical field's unnamed default.
682    fn replace_table_field_analyzer_binding(
683        &self,
684        _table: &str,
685        _field: &str,
686        _phase: &str,
687        _name: &str,
688        _binding_json: &str,
689    ) -> StorageBackendResult<()> {
690        Err(StorageBackendError::Other(
691            "durable analyzer bindings are not supported by this catalog".into(),
692        ))
693    }
694
695    /// `(table, field, binding JSON)` rows. Each field has one complete binding envelope.
696    fn load_table_field_analyzer_bindings(
697        &self,
698    ) -> StorageBackendResult<Vec<(String, String, String)>> {
699        Ok(Vec::new())
700    }
701
702    fn save_table_field_analyzer(
703        &self,
704        table_name: &str,
705        field: &str,
706        phase: &str,
707        analyzer_name: &str,
708    ) -> StorageBackendResult<()>;
709    fn replace_table_field_analyzer(
710        &self,
711        table_name: &str,
712        field: &str,
713        phase: &str,
714        analyzer_name: &str,
715    ) -> StorageBackendResult<()>;
716    fn drop_table_field_analyzer_field(
717        &self,
718        table_name: &str,
719        field: &str,
720    ) -> StorageBackendResult<()>;
721    fn drop_table_field_analyzers(&self, table_name: &str) -> StorageBackendResult<()>;
722    fn load_table_field_analyzers(
723        &self,
724    ) -> StorageBackendResult<Vec<(String, String, String, String)>>;
725
726    fn save_foreign_server(
727        &self,
728        name: &str,
729        fdw_type: &str,
730        options_json: &str,
731    ) -> StorageBackendResult<()>;
732    fn drop_foreign_server(&self, name: &str) -> StorageBackendResult<()>;
733    fn load_foreign_servers(&self) -> StorageBackendResult<Vec<(String, String, String)>>;
734
735    /// Atomically replace a complete foreign-server row. A catalog without metadata support must reject it instead of discarding the metadata.
736    fn save_foreign_server_row(&self, row: &ForeignServerRow) -> StorageBackendResult<()> {
737        if row.metadata_json.is_some() {
738            return Err(StorageBackendError::Other(
739                "foreign-server metadata is not supported by this catalog".into(),
740            ));
741        }
742        self.save_foreign_server(&row.name, &row.fdw_type, &row.options_json)
743    }
744
745    /// Read definitions and their metadata from one catalog view. Legacy implementations expose absent metadata explicitly.
746    fn load_foreign_server_rows(&self) -> StorageBackendResult<Vec<ForeignServerRow>> {
747        Ok(self
748            .load_foreign_servers()?
749            .into_iter()
750            .map(|(name, fdw_type, options_json)| ForeignServerRow {
751                name,
752                fdw_type,
753                options_json,
754                metadata_json: None,
755            })
756            .collect())
757    }
758
759    fn save_foreign_table(&self, row: &ForeignTableRow) -> StorageBackendResult<()>;
760    /// Atomically move one foreign-table catalog row and its shared relation claim.
761    fn rename_foreign_table(
762        &self,
763        from: &RelationIdentity,
764        to: &RelationIdentity,
765    ) -> StorageBackendResult<bool>;
766    fn update_foreign_table_security(
767        &self,
768        relation: &RelationIdentity,
769        security: &RelationSecurityRow,
770    ) -> StorageBackendResult<bool>;
771    fn drop_foreign_table(&self, relation: &RelationIdentity) -> StorageBackendResult<()>;
772    fn load_foreign_tables(&self) -> StorageBackendResult<Vec<ForeignTableRow>>;
773
774    fn save_catalog_index(
775        &self,
776        relation: &RelationIdentity,
777        index_type: &str,
778        table_name: &str,
779        columns_json: &str,
780        parameters_json: &str,
781    ) -> StorageBackendResult<()> {
782        self.save_catalog_index_row(&CatalogIndexRow {
783            relation: relation.clone(),
784            index_type: index_type.to_string(),
785            table_name: table_name.to_string(),
786            columns_json: columns_json.to_string(),
787            parameters_json: parameters_json.to_string(),
788            definition_json: None,
789        })
790    }
791    fn save_catalog_index_row(&self, index: &CatalogIndexRow) -> StorageBackendResult<()>;
792    fn drop_catalog_index(&self, relation: &RelationIdentity) -> StorageBackendResult<()>;
793    fn drop_catalog_indexes_for_table(&self, table_name: &str) -> StorageBackendResult<()>;
794    fn load_catalog_indexes(&self) -> StorageBackendResult<Vec<CatalogIndexRow>>;
795
796    fn save_path_index(
797        &self,
798        graph_name: &str,
799        label_sequences_json: &str,
800    ) -> StorageBackendResult<()>;
801    fn drop_path_index(&self, graph_name: &str) -> StorageBackendResult<()>;
802    fn load_path_indexes(&self) -> StorageBackendResult<Vec<(String, String)>>;
803
804    /// Durable reachability records, paged lexicographically by (source, target).
805    /// Building calls clear, bounded saves, then finish inside one transaction.
806    /// Graph mutations invalidate the materialization atomically; definitions remain.
807    fn clear_path_index_data(&self, index: &str) -> StorageBackendResult<()>;
808    fn save_path_index_pairs(
809        &self,
810        index: &str,
811        sequence: &str,
812        pairs: &[(u64, u64)],
813    ) -> StorageBackendResult<()>;
814    fn finish_path_index_data(
815        &self,
816        index: &str,
817        graph: &str,
818        definition: &str,
819    ) -> StorageBackendResult<()>;
820    fn path_index_data_is_current(
821        &self,
822        index: &str,
823        definition: &str,
824    ) -> StorageBackendResult<bool>;
825    fn path_index_pairs(
826        &self,
827        index: &str,
828        sequence: &str,
829        after: Option<(u64, u64)>,
830        limit: usize,
831    ) -> StorageBackendResult<Vec<(u64, u64)>>;
832
833    fn save_column_stats(&self, stats: ColumnStatsInput<'_>) -> StorageBackendResult<()>;
834    /// Atomically replace the complete statistics snapshot for one table.
835    /// Implementations must leave the prior snapshot intact if any row fails.
836    fn replace_column_stats(
837        &self,
838        table_name: &str,
839        stats: &[ColumnStatsInput<'_>],
840    ) -> StorageBackendResult<()>;
841    fn load_column_stats(&self, table_name: &str) -> StorageBackendResult<Vec<ColumnStatsRow>>;
842    fn delete_column_stats(&self, table_name: &str) -> StorageBackendResult<()>;
843}
844
845#[cfg(test)]
846mod tests {
847    use super::RelationIdentity;
848
849    #[test]
850    fn relation_identity_rendering_is_reversible_and_collision_free() {
851        let left = RelationIdentity::new("a.b", "c");
852        let right = RelationIdentity::new("a", "b.c");
853        assert_eq!(left.qualified_name(), "\"a.b\".c");
854        assert_eq!(right.qualified_name(), "a.\"b.c\"");
855        assert_ne!(left.qualified_name(), right.qualified_name());
856        assert_eq!(
857            RelationIdentity::from_legacy_name(&left.qualified_name()).unwrap(),
858            left
859        );
860        assert_eq!(
861            RelationIdentity::from_legacy_name(&right.qualified_name()).unwrap(),
862            right
863        );
864    }
865
866    #[test]
867    fn relation_identity_preserves_quotes_and_unqualified_public_alias() {
868        let quoted = RelationIdentity::new("public", "a\"b.c");
869        assert_eq!(quoted.qualified_name(), "public.\"a\"\"b.c\"");
870        assert_eq!(
871            quoted.canonical_and_legacy_public_names(),
872            vec![
873                "public.\"a\"\"b.c\"".to_string(),
874                "\"a\"\"b.c\"".to_string()
875            ]
876        );
877        assert_eq!(
878            RelationIdentity::from_legacy_name(&quoted.qualified_name()).unwrap(),
879            quoted
880        );
881        assert_eq!(
882            RelationIdentity::from_legacy_name("plain").unwrap(),
883            RelationIdentity::new("public", "plain")
884        );
885        assert_eq!(
886            RelationIdentity::new("app", "plain").canonical_and_legacy_public_names(),
887            vec!["app.plain".to_string()]
888        );
889        assert_eq!(
890            RelationIdentity::new("public", "Upper").canonical_and_legacy_public_names(),
891            vec![
892                "public.\"Upper\"".to_string(),
893                "\"Upper\"".to_string(),
894                "Upper".to_string()
895            ]
896        );
897    }
898}