Skip to main content

uqa_engine/capabilities/
enums.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind enum DDL to namespace, identity, publication and transaction visibility state.
8
9use crate::Engine;
10use std::collections::BTreeMap;
11use uqa_execution::catalog::enum_type::{EnumRegistry, EnumRegistryPublication, EnumRegistryRead};
12use uqa_execution::schema::enums::{EnumLabelVisibility, EnumTypeContext};
13use uqa_sql::catalog::roles::RoleDefinition;
14use uqa_sql::expr::enums::{EnumLabelCatalog, EnumTypeLabels};
15use uqa_sql::schema::domains::removal::TypeObjectBinding;
16use uqa_sql::SQLError;
17
18impl Engine {
19    pub(crate) fn enum_type_context(&self) -> EnumTypeContext<'_> {
20        EnumTypeContext {
21            shells: self.shell_completion_context(),
22            creation: self.relation_creation_context(),
23            identities: self.catalog_identity_reservation_context(),
24            writer: self,
25            binding: TypeObjectBinding {
26                catalog: self,
27                authority: self,
28                session: self,
29            },
30            allocate_identity: || {
31                crate::new_nonzero_catalog_identity("enum", "object identity")
32                    .map_err(|error| SQLError::Internal(error.to_string()))
33            },
34            publication: self,
35            domains: self,
36            composites: self,
37            changes: self,
38            visibility: self,
39            notices: self,
40        }
41    }
42}
43
44impl Engine {
45    /// Enum definitions restore before domains and relations, whose declared types can refer to them.
46    pub(crate) fn restore_enums_from_catalog(
47        &self,
48        catalog: &dyn uqa_storage::CatalogFacade,
49    ) -> uqa_storage::StorageBackendResult<()> {
50        let registry =
51            uqa_execution::catalog::enum_type::restore(catalog, &self.durable.roles.read())?;
52        *self.durable.enums.write() = registry;
53        Ok(())
54    }
55}
56
57impl Engine {
58    /// The enum registry generation of the running statement: the pinned query snapshot when one exists, otherwise the session's current definitions.
59    pub(crate) fn enum_registry_snapshot(&self) -> std::sync::Arc<EnumRegistry> {
60        self.query_catalog_snapshot.as_ref().map_or_else(
61            || self.durable.enums.snapshot(),
62            |snapshot| std::sync::Arc::clone(&snapshot.enums),
63        )
64    }
65}
66
67impl Engine {
68    /// Replace the enum values of a query result by their current labels, as `PostgreSQL` clients receive them from the type's output function. Declared column types keep the enum type.
69    ///
70    /// # Errors
71    ///
72    /// Returns an error when a result value names an enum type or label that this session's catalog no longer contains.
73    pub fn render_enum_labels(&self, result: &mut uqa_sql::SQLResult) -> Result<(), SQLError> {
74        uqa_sql::result::render_result_enum_labels(Some(self), result)
75    }
76}
77
78impl EnumLabelCatalog for Engine {
79    fn compare_range_bounds(
80        &self,
81        range_oid: u32,
82        left: &uqa_core::Value,
83        right: &uqa_core::Value,
84        control: &uqa_core::memory::ProductionControl<'_>,
85    ) -> Result<std::cmp::Ordering, SQLError> {
86        uqa_execution::catalog::range_type::support::compare_bounds(
87            &self.catalog_read_view(),
88            self,
89            Some(&self.session.range_comparison_states),
90            range_oid,
91            (left, right),
92            control,
93        )
94    }
95
96    fn range_bound_equality_key(
97        &self,
98        range_oid: u32,
99        value: &uqa_core::Value,
100        control: &uqa_core::memory::ProductionControl<'_>,
101    ) -> Result<uqa_core::memory::Produced<Vec<u8>>, SQLError> {
102        uqa_execution::catalog::range_type::support::bound_equality_key(
103            &self.catalog_read_view(),
104            self,
105            range_oid,
106            value,
107            control,
108        )
109    }
110
111    fn value_range_type(
112        &self,
113        oid: u32,
114    ) -> Result<Option<std::sync::Arc<uqa_sql::expr::RangeValueDescriptor>>, SQLError> {
115        self.catalog_read_view().range_value_descriptor(oid)
116    }
117
118    fn value_type_by_oid_with_control(
119        &self,
120        oid: u32,
121        control: &uqa_core::memory::ProductionControl<'_>,
122    ) -> Result<Option<uqa_core::memory::Produced<uqa_sql::ColumnType>>, SQLError> {
123        uqa_sql::expr::EngineHook::resolve_type_oid_with_control(self, oid, control)
124    }
125
126    fn value_type_by_oid(&self, oid: u32) -> Result<Option<uqa_sql::ColumnType>, SQLError> {
127        uqa_sql::expr::EngineHook::resolve_type_oid(self, oid).map_err(SQLError::Internal)
128    }
129
130    fn value_type_exists(&self, oid: u32) -> Result<bool, SQLError> {
131        uqa_execution::catalog::projection::type_oid_exists(&self.catalog_execution(), oid)
132    }
133
134    fn value_composite_type(
135        &self,
136        oid: u32,
137    ) -> Result<Option<std::sync::Arc<uqa_sql::expr::composites::CompositeTypeDescriptor>>, SQLError>
138    {
139        uqa_sql::expr::composites::CompositeTypeCatalog::composite_type(self, oid)
140    }
141
142    fn value_composite_type_with_control(
143        &self,
144        oid: u32,
145        control: &uqa_core::memory::ProductionControl<'_>,
146    ) -> Result<Option<uqa_sql::expr::composites::OwnedCompositeTypeDescriptor>, SQLError> {
147        uqa_sql::expr::composites::CompositeTypeCatalog::composite_type_with_control(
148            self, oid, control,
149        )
150    }
151
152    fn enum_type_comparison_states(
153        &self,
154    ) -> Option<&uqa_sql::expr::enums::EnumTypeComparisonStates> {
155        Some(&self.session.enum_type_comparison_states)
156    }
157
158    fn enum_label_position(&self, label_oid: u32) -> Result<Option<(u32, usize)>, SQLError> {
159        Ok(self
160            .runtime
161            .enum_label_cache
162            .position(&self.enum_registry_snapshot(), label_oid))
163    }
164
165    fn enum_value_by_oid(&self, label_oid: u32) -> Result<Option<uqa_core::EnumValue>, SQLError> {
166        Ok(self
167            .runtime
168            .enum_label_cache
169            .value(&self.enum_registry_snapshot(), label_oid))
170    }
171
172    fn enum_type_labels(
173        &self,
174        type_oid: u32,
175    ) -> Result<Option<std::sync::Arc<EnumTypeLabels>>, SQLError> {
176        Ok(self
177            .runtime
178            .enum_label_cache
179            .labels(&self.enum_registry_snapshot(), type_oid))
180    }
181
182    /// Labels added by the outermost transaction to a type it did not create stay unusable until commit.
183    fn enum_label_uncommitted(&self, label_oid: u32) -> bool {
184        self.session
185            .uncommitted_enum_labels
186            .lock()
187            .is_uncommitted(label_oid)
188    }
189
190    /// The regtype spelling of an enum, read from the enum registry alone: label errors are raised while catalog restoration holds transaction state, where building the complete catalog projection must not be attempted.
191    fn enum_type_name(&self, type_oid: u32) -> Result<Option<String>, SQLError> {
192        let registry = self.enum_registry_snapshot();
193        let Some(definition) = registry
194            .values()
195            .find(|definition| definition.oid == type_oid)
196        else {
197            return Ok(None);
198        };
199        let name = uqa_sql::expr::quote_ident(&definition.identity.name);
200        let schema = &definition.identity.schema;
201        let visible = schema == "pg_catalog"
202            || self
203                .session
204                .state
205                .read()
206                .search_path
207                .iter()
208                .any(|entry| entry == schema);
209        Ok(Some(if visible {
210            name
211        } else {
212            format!("{}.{name}", uqa_sql::expr::quote_ident(schema))
213        }))
214    }
215
216    fn has_enum_types(&self) -> bool {
217        !self.enum_registry_snapshot().is_empty()
218    }
219}
220
221impl EnumRegistryPublication for Engine {
222    fn enum_registry(&self) -> EnumRegistryRead<'_> {
223        Box::new(self.durable.enums.read())
224    }
225    fn enum_catalog(&self) -> Option<&dyn uqa_storage::CatalogFacade> {
226        self.storage.catalog.as_deref()
227    }
228    fn enum_role_definitions(&self) -> BTreeMap<String, RoleDefinition> {
229        self.durable.roles.read().clone()
230    }
231    fn publish_enum_definitions(&self, registry: EnumRegistry) {
232        *self.durable.enums.write() = registry;
233    }
234}
235
236impl EnumLabelVisibility for Engine {
237    fn enum_type_created(&self, type_oid: u32) {
238        if !self.session.transactions.lock().is_empty() {
239            self.session
240                .uncommitted_enum_labels
241                .lock()
242                .type_created(type_oid);
243        }
244    }
245    fn enum_label_added(&self, type_oid: u32, label_oid: u32) {
246        if !self.session.transactions.lock().is_empty() {
247            self.session
248                .uncommitted_enum_labels
249                .lock()
250                .label_added(type_oid, label_oid);
251        }
252    }
253}