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