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