Skip to main content

uqa_execution/catalog/
services.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Consumer-owned services required to project catalog rows.
8use super::RelationNameResolution;
9use uqa_core::Value;
10use uqa_sql::catalog::roles::RoleReference;
11use uqa_sql::catalog::session::{CursorMetadata, PreparedStatementMetadata};
12use uqa_sql::{
13    ast::{Expr, TriggerEvent},
14    SQLError,
15};
16
17pub trait CatalogSession: Sync {
18    fn current_role(&self) -> RoleReference;
19    fn temporary_schema_name(&self) -> String;
20    fn relation_name_resolution(&self) -> RelationNameResolution;
21    /// Native sessions admit copies directly from locked session state; external services may supply their existing owned snapshot.
22    fn relation_name_resolution_with_control(
23        &self,
24        control: &uqa_core::memory::ProductionControl<'_>,
25    ) -> Result<uqa_core::memory::Produced<RelationNameResolution>, SQLError> {
26        self.relation_name_resolution().copy_with_control(control)
27    }
28    /// The canonical name of the parameter `name` refers to and its value as `SHOW` reports it.
29    fn show_parameter(&self, name: &str) -> Result<(String, String), SQLError>;
30    /// Describe a SHOW column without constructing its current setting. External services preserve their existing resolution callback.
31    fn parameter_name_with_control(
32        &self,
33        name: &str,
34        control: &uqa_core::memory::ProductionControl<'_>,
35    ) -> Result<uqa_core::memory::Produced<String>, SQLError> {
36        control.check()?;
37        let (name, _) = self.show_parameter(name)?;
38        Ok(control.copy_text(&name)?)
39    }
40
41    /// Every parameter that `SHOW ALL` and `pg_settings` report, in name order.
42    fn parameter_settings(&self) -> Vec<uqa_sql::semantics::parameters::setting::ParameterSetting>;
43    /// Native sessions override this boundary to read only selected planning parameters. An external implementation may supply its existing settings snapshot.
44    fn explain_settings(
45        &self,
46        control: &uqa_core::memory::ProductionControl<'_>,
47    ) -> Result<
48        uqa_core::memory::Produced<uqa_sql::semantics::parameters::explain::ExplainSettings>,
49        SQLError,
50    > {
51        let settings = self.parameter_settings();
52        uqa_sql::semantics::parameters::explain::capture(
53            &|definition, control| {
54                settings
55                    .iter()
56                    .find(|setting| setting.definition.name == definition.name)
57                    .map(|setting| control.copy_text(&setting.setting).map_err(Into::into))
58                    .transpose()
59            },
60            control,
61        )
62    }
63    fn prepared_statements(&self) -> Vec<PreparedStatementMetadata>;
64    fn cursors(&self) -> Vec<CursorMetadata>;
65}
66pub trait CatalogExpressionEvaluation: Sync {
67    fn evaluate(&self, expression: &Expr) -> Result<Value, SQLError>;
68}
69pub trait RelationCounts: Sync {
70    fn table_doc_count(&self, table: &str) -> Result<u64, SQLError>;
71}
72pub use uqa_sql::catalog::view::ViewMutationCapabilities;
73pub struct ViewCatalogMetadata {
74    pub catalog: ViewMutationCapabilities,
75    pub catalog_columns: Vec<bool>,
76    pub check_option: String,
77}
78pub trait ViewCatalogCapabilities: Sync {
79    fn view_updatability(&self, name: &str) -> Result<ViewCatalogMetadata, SQLError>;
80    fn has_instead_of_trigger(&self, name: &str, event: TriggerEvent) -> Result<bool, SQLError>;
81    fn view_updatability_with_catalog(
82        &self,
83        name: &str,
84        _catalog: &super::CatalogReadView,
85        _resolution: &RelationNameResolution,
86    ) -> Result<ViewCatalogMetadata, SQLError> {
87        self.view_updatability(name)
88    }
89    fn has_instead_of_trigger_with_catalog(
90        &self,
91        name: &str,
92        event: TriggerEvent,
93        _catalog: &super::CatalogReadView,
94        _resolution: &RelationNameResolution,
95    ) -> Result<bool, SQLError> {
96        self.has_instead_of_trigger(name, event)
97    }
98}
99
100pub trait CatalogNamespace: Sync {
101    fn current_schema_names(&self, include_implicit: bool) -> Result<Vec<String>, SQLError>;
102    /// Resolve visibility through a caller-selected catalog while preserving legacy namespace services.
103    fn current_schema_names_with_catalog(
104        &self,
105        _catalog: &super::CatalogReadView,
106        include_implicit: bool,
107    ) -> Result<Vec<String>, SQLError> {
108        self.current_schema_names(include_implicit)
109    }
110}
111
112pub trait CatalogSnapshotSource: Sync {
113    fn catalog_snapshot(&self) -> super::CatalogReadView;
114    /// Capture builtin authority at the same boundary as ordinary catalog reads. Sources may use immutable authority inputs when they prove the existing unrestricted rule without table metadata.
115    fn builtin_routine_permissions(
116        &self,
117        current_role: RoleReference,
118    ) -> super::security::builtin_routines::execution::BuiltinRoutinePermissions {
119        super::security::builtin_routines::execution::BuiltinRoutinePermissions::new(
120            self.catalog_snapshot(),
121            current_role,
122        )
123    }
124    fn refreshed_catalog_snapshot(&self) -> Result<super::CatalogReadView, SQLError>;
125    /// Refresh definitions without capturing a query view that definition coordination will discard.
126    fn refresh_catalog(&self) -> Result<(), SQLError> {
127        self.refreshed_catalog_snapshot().map(|_| ())
128    }
129    /// Attach the original query participant without replacing the retained catalog or observing unused sources.
130    fn bind_query_reads(
131        &self,
132        snapshot: super::CatalogReadView,
133    ) -> Result<super::CatalogReadView, SQLError> {
134        Ok(snapshot)
135    }
136    /// Retain direct catalog rows independently of name binding and SSI attribution.
137    fn retain_catalog_rows(
138        &self,
139        snapshot: super::CatalogReadView,
140    ) -> Result<super::CatalogReadView, SQLError> {
141        Ok(snapshot)
142    }
143    /// Definition coordination uses the refreshed session catalog, independently from an ordinary query's retained snapshot.
144    fn current_catalog_snapshot(&self) -> super::CatalogReadView;
145    /// A session-local revision covering all visible definition changes, including private DDL, rollback and refresh after a catalog lock wait. Sources without this guarantee must return `None`.
146    fn current_catalog_revision(&self) -> Option<u64> {
147        None
148    }
149}
150impl CatalogSnapshotSource for super::CatalogReadView {
151    fn current_catalog_revision(&self) -> Option<u64> {
152        Some(0)
153    }
154    fn refresh_catalog(&self) -> Result<(), SQLError> {
155        Ok(())
156    }
157    fn current_catalog_snapshot(&self) -> super::CatalogReadView {
158        self.clone()
159    }
160    fn refreshed_catalog_snapshot(&self) -> Result<super::CatalogReadView, SQLError> {
161        Ok(self.clone())
162    }
163    fn catalog_snapshot(&self) -> super::CatalogReadView {
164        self.clone()
165    }
166}