Skip to main content

uqa_execution/catalog/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Immutable catalog inputs and runtime catalog projections.
8
9pub mod comments;
10pub mod composite_type;
11pub mod domain;
12pub mod enum_type;
13pub mod foreign;
14pub mod identity;
15pub mod range_type;
16pub mod security;
17pub mod sequence;
18pub mod shell_type;
19pub mod tuples;
20pub mod type_identity_restoration;
21pub(crate) mod type_records;
22pub mod value_restoration;
23pub mod view;
24
25use security::{
26    BoundDatabaseSecurity, BoundSchemaSecurity, BoundSequenceSecurity, BoundTableSecurity,
27};
28use sequence::SequenceState;
29use std::collections::BTreeMap;
30use std::sync::Arc;
31use uqa_core::RelationIdentity;
32pub use uqa_sql::catalog::resolution::{RelationLookupMode, RelationNameResolution};
33use view::StoredView;
34mod analysis;
35pub mod definition_revision;
36pub mod graph;
37pub mod graph_oids;
38mod graph_reads;
39pub mod namespaces;
40mod prepared_dependencies;
41mod read;
42pub mod relation_names;
43pub mod schema;
44mod snapshot_read;
45
46/// Immutable catalog inputs with optional query read attribution. This view cannot change definitions, coordinate DDL, publish caches, or recover the enclosing engine.
47#[derive(Clone)]
48pub struct CatalogReadView {
49    snapshot: Arc<CatalogReadSnapshot>,
50    relation_descriptors: Arc<composite_type::relations::RelationDescriptorCache>,
51    range_descriptors: Option<Arc<range_type::RangeDescriptors>>,
52    dependencies: Arc<projection::DependencyCatalogCache>,
53    index_relations: Arc<cache::CatalogDerivation<projection::IndexRelations>>,
54    constraint_definitions: Arc<cache::CatalogDerivation<projection::ConstraintDefinitions>>,
55    event_definitions: Arc<projection::EventDefinitions>,
56    routine_definitions: Arc<projection::RoutineDefinitions>,
57    alias_output: Arc<cache::CatalogDerivation<Arc<projection::RegtypeOutputCatalog>>>,
58    graph_reads: Option<Arc<graph_reads::GraphCatalogRead>>,
59    /// The owning session's catalog records, read only inside its retained statement transaction.
60    prepared_catalog: Option<Arc<dyn uqa_storage::CatalogFacade>>,
61    /// Physical system-catalog rows at the query's committed boundary and private root. Current name/authority inquiries continue to use definitions.
62    physical_catalog: Option<Arc<dyn uqa_storage::CatalogFacade>>,
63    /// The exact positions of sequences whose durable records run ahead of the values handed out. They move without a catalog change, so they are read when a sequence's values are.
64    sequence_positions: Option<Arc<crate::row_locks::RowLockManager>>,
65    /// The committed value records of sequences, which also move without a catalog change. A sequence's state is read from them when no position covers it.
66    latest_sequence_values: Option<Arc<dyn sequence::latest_values::LatestSequenceValues>>,
67}
68
69/// Immutable catalog names and durable registries captured at one statement boundary.
70#[derive(Clone)]
71pub struct CatalogReadSnapshot {
72    pub tables: BTreeMap<uqa_core::RelationIdentity, CatalogTableSnapshot>,
73    pub definitions: CatalogDefinitionSnapshot,
74    /// The session's temporary namespace once its first temporary object created it.
75    pub temporary_namespace: Option<uqa_sql::catalog::temporary_namespace::TemporaryNamespace>,
76}
77
78/// Immutable table-definition fields used by binding and catalog projection.
79#[derive(Clone)]
80pub struct CatalogTableSnapshot {
81    pub dropped_attributes: Arc<Vec<uqa_sql::catalog::relation_attributes::DroppedAttribute>>,
82    pub object_id: [u8; 16],
83    /// The table's public OIDs, recorded or derived from its identity.
84    pub catalog_oids: uqa_sql::catalog::relation_oids::RelationCatalogOids,
85    pub row_type_array_name: Option<String>,
86    pub security: Arc<crate::catalog::security::BoundTableSecurity>,
87    pub columns: Arc<Vec<uqa_sql::ast::ColumnDef>>,
88    pub columns_declared: bool,
89    pub checks: Arc<Vec<uqa_sql::ast::TableCheck>>,
90    pub foreign_keys: Arc<Vec<uqa_sql::ast::ForeignKey>>,
91    pub keys: Arc<Vec<uqa_sql::ast::TableKeyConstraint>>,
92    pub hierarchy: Arc<uqa_sql::ast::TableHierarchy>,
93    pub persistence: uqa_sql::ast::RelationPersistence,
94}
95
96/// Immutable state for one sequence selected through the statement's relation namespace.
97#[derive(Clone)]
98pub struct CatalogSequenceSnapshot {
99    pub relation: uqa_core::RelationIdentity,
100    pub state: crate::catalog::sequence::SequenceState,
101    pub security: crate::catalog::security::SequenceSecurity,
102}
103
104pub type CatalogSequenceMetadata = (
105    String,
106    uqa_sql::ast::RelationPersistence,
107    [u8; 16],
108    security::SequenceSecurity,
109);
110
111pub use uqa_sql::catalog::resolution::RelationResolution;
112
113/// Shared immutable definition maps captured from one catalog generation.
114#[derive(Clone)]
115pub struct CatalogDefinitionSnapshot {
116    pub builtin_routine_security:
117        Arc<uqa_sql::catalog::security::builtin_routines::BuiltinRoutineSecurities>,
118    pub sequence_persistence: Arc<BTreeMap<RelationIdentity, uqa_sql::ast::RelationPersistence>>,
119    pub foreign_tables: Arc<BTreeMap<RelationIdentity, foreign::StoredForeignTable>>,
120    pub foreign_wrappers: Arc<uqa_sql::catalog::foreign_wrapper::ForeignWrappers>,
121    pub foreign_servers:
122        Arc<BTreeMap<String, uqa_sql::catalog::foreign_server::ForeignServerDefinition>>,
123    pub sql_user_functions: Arc<BTreeMap<String, Vec<Arc<uqa_sql::routines::SQLUserFunction>>>>,
124    pub role_memberships: Arc<
125        BTreeMap<
126            uqa_sql::catalog::roles::RoleMembershipKey,
127            uqa_sql::catalog::roles::RoleMembership,
128        >,
129    >,
130
131    pub domains: Arc<BTreeMap<String, uqa_sql::catalog::domain::StoredDomain>>,
132    pub enums: Arc<enum_type::EnumRegistry>,
133    pub ranges: Arc<range_type::RangeRegistry>,
134    pub shells: Arc<shell_type::ShellRegistry>,
135    pub comments: Arc<comments::CommentRegistry>,
136    pub composites: Arc<composite_type::CompositeRegistry>,
137    pub graphs: Arc<BTreeMap<String, Arc<uqa_graph::GraphStoreHandle>>>,
138    pub views: Arc<BTreeMap<RelationIdentity, StoredView>>,
139    pub catalog_indexes: Arc<BTreeMap<RelationIdentity, uqa_storage::CatalogIndexRow>>,
140    pub database_security: Arc<BoundDatabaseSecurity>,
141    pub schemas: Arc<BTreeMap<String, BoundSchemaSecurity>>,
142    pub sequences: Arc<BTreeMap<RelationIdentity, SequenceState>>,
143    pub sequence_object_ids: Arc<BTreeMap<RelationIdentity, [u8; 16]>>,
144    /// The `pg_class` OIDs sequences recorded when they were created, by object identity.
145    pub sequence_catalog_oids: Arc<BTreeMap<[u8; 16], u32>>,
146    /// The OIDs graphs and their labels recorded when they were created, by graph name.
147    pub graph_catalog_oids: Arc<BTreeMap<String, uqa_sql::catalog::graph_oids::GraphCatalogOids>>,
148    pub sequence_security: Arc<BTreeMap<RelationIdentity, BoundSequenceSecurity>>,
149    pub foreign_table_security: Arc<BTreeMap<RelationIdentity, BoundTableSecurity>>,
150    pub system_relation_security:
151        Arc<uqa_sql::catalog::security::system_relations::SystemRelationSecurities>,
152    pub roles: Arc<BTreeMap<String, uqa_sql::catalog::roles::RoleDefinition>>,
153    pub triggers: Arc<
154        BTreeMap<
155            uqa_storage::RelationIdentity,
156            BTreeMap<String, uqa_sql::catalog::events::StoredTrigger>,
157        >,
158    >,
159    pub rules: Arc<
160        BTreeMap<
161            uqa_storage::RelationIdentity,
162            BTreeMap<String, uqa_sql::catalog::events::StoredRule>,
163        >,
164    >,
165}
166
167impl CatalogReadView {
168    pub fn new(snapshot: CatalogReadSnapshot) -> Self {
169        let range_descriptors = (!snapshot.definitions.ranges.is_empty()).then(Arc::default);
170        Self {
171            snapshot: Arc::new(snapshot),
172            relation_descriptors: Arc::default(),
173            range_descriptors,
174            dependencies: Arc::default(),
175            index_relations: Arc::default(),
176            constraint_definitions: Arc::default(),
177            event_definitions: Arc::default(),
178            routine_definitions: Arc::default(),
179            alias_output: Arc::default(),
180            graph_reads: None,
181            prepared_catalog: None,
182            physical_catalog: None,
183            sequence_positions: None,
184            latest_sequence_values: None,
185        }
186    }
187
188    #[must_use]
189    pub fn with_sequence_positions(
190        mut self,
191        positions: Arc<crate::row_locks::RowLockManager>,
192    ) -> Self {
193        self.sequence_positions = Some(positions);
194        self
195    }
196
197    #[must_use]
198    pub fn with_latest_sequence_values(
199        mut self,
200        values: Arc<dyn sequence::latest_values::LatestSequenceValues>,
201    ) -> Self {
202        self.latest_sequence_values = Some(values);
203        self
204    }
205    #[must_use]
206    pub fn with_prepared_catalog(mut self, catalog: Arc<dyn uqa_storage::CatalogFacade>) -> Self {
207        self.prepared_catalog = Some(catalog);
208        self
209    }
210
211    pub fn snapshot(&self) -> &CatalogReadSnapshot {
212        &self.snapshot
213    }
214
215    #[must_use]
216    pub fn with_physical_catalog(mut self, catalog: Arc<dyn uqa_storage::CatalogFacade>) -> Self {
217        self.physical_catalog = Some(catalog);
218        self
219    }
220
221    pub fn has_physical_catalog(&self) -> bool {
222        self.physical_catalog.is_some()
223    }
224}
225
226pub mod cache;
227pub mod context;
228pub mod index;
229pub mod projection;
230pub mod services;
231
232pub mod sequence_introspection;
233
234#[cfg(test)]
235pub(crate) mod test_support;
236
237pub mod notices;