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(&self, oid: u32) -> Result<Option<uqa_sql::ColumnType>, SQLError> {
119        uqa_sql::expr::EngineHook::resolve_type_oid(self, oid).map_err(SQLError::Internal)
120    }
121
122    fn value_type_exists(&self, oid: u32) -> Result<bool, SQLError> {
123        uqa_execution::catalog::projection::type_oid_exists(&self.catalog_execution(), oid)
124    }
125
126    fn value_composite_type(
127        &self,
128        oid: u32,
129    ) -> Result<Option<std::sync::Arc<uqa_sql::expr::composites::CompositeTypeDescriptor>>, SQLError>
130    {
131        uqa_sql::expr::composites::CompositeTypeCatalog::composite_type(self, oid)
132    }
133
134    fn enum_type_comparison_states(
135        &self,
136    ) -> Option<&uqa_sql::expr::enums::EnumTypeComparisonStates> {
137        Some(&self.session.enum_type_comparison_states)
138    }
139
140    fn enum_label_position(&self, label_oid: u32) -> Result<Option<(u32, usize)>, SQLError> {
141        Ok(self
142            .runtime
143            .enum_label_cache
144            .position(&self.enum_registry_snapshot(), label_oid))
145    }
146
147    fn enum_value_by_oid(&self, label_oid: u32) -> Result<Option<uqa_core::EnumValue>, SQLError> {
148        Ok(self
149            .runtime
150            .enum_label_cache
151            .value(&self.enum_registry_snapshot(), label_oid))
152    }
153
154    fn enum_type_labels(
155        &self,
156        type_oid: u32,
157    ) -> Result<Option<std::sync::Arc<EnumTypeLabels>>, SQLError> {
158        Ok(self
159            .runtime
160            .enum_label_cache
161            .labels(&self.enum_registry_snapshot(), type_oid))
162    }
163
164    /// Labels added by the outermost transaction to a type it did not create stay unusable until commit.
165    fn enum_label_uncommitted(&self, label_oid: u32) -> bool {
166        self.session
167            .uncommitted_enum_labels
168            .lock()
169            .is_uncommitted(label_oid)
170    }
171
172    /// 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.
173    fn enum_type_name(&self, type_oid: u32) -> Result<Option<String>, SQLError> {
174        let registry = self.enum_registry_snapshot();
175        let Some(definition) = registry
176            .values()
177            .find(|definition| definition.oid == type_oid)
178        else {
179            return Ok(None);
180        };
181        let name = uqa_sql::expr::quote_ident(&definition.identity.name);
182        let schema = &definition.identity.schema;
183        let visible = schema == "pg_catalog"
184            || self
185                .session
186                .state
187                .read()
188                .search_path
189                .iter()
190                .any(|entry| entry == schema);
191        Ok(Some(if visible {
192            name
193        } else {
194            format!("{}.{name}", uqa_sql::expr::quote_ident(schema))
195        }))
196    }
197
198    fn has_enum_types(&self) -> bool {
199        !self.enum_registry_snapshot().is_empty()
200    }
201}
202
203impl EnumRegistryPublication for Engine {
204    fn enum_registry(&self) -> EnumRegistryRead<'_> {
205        Box::new(self.durable.enums.read())
206    }
207    fn enum_catalog(&self) -> Option<&dyn uqa_storage::CatalogFacade> {
208        self.storage.catalog.as_deref()
209    }
210    fn enum_role_definitions(&self) -> BTreeMap<String, RoleDefinition> {
211        self.durable.roles.read().clone()
212    }
213    fn publish_enum_definitions(&self, registry: EnumRegistry) {
214        *self.durable.enums.write() = registry;
215    }
216}
217
218impl EnumLabelVisibility for Engine {
219    fn enum_type_created(&self, type_oid: u32) {
220        if !self.session.transactions.lock().is_empty() {
221            self.session
222                .uncommitted_enum_labels
223                .lock()
224                .type_created(type_oid);
225        }
226    }
227    fn enum_label_added(&self, type_oid: u32, label_oid: u32) {
228        if !self.session.transactions.lock().is_empty() {
229            self.session
230                .uncommitted_enum_labels
231                .lock()
232                .label_added(type_oid, label_oid);
233        }
234    }
235}