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    /// The canonical name of the parameter `name` refers to and its value as `SHOW` reports it.
22    fn show_parameter(&self, name: &str) -> Result<(String, String), SQLError>;
23    /// Every parameter that `SHOW ALL` and `pg_settings` report, in name order.
24    fn parameter_settings(&self) -> Vec<uqa_sql::semantics::parameters::setting::ParameterSetting>;
25    /// Native sessions override this boundary to read only selected planning parameters. An external implementation may supply its existing settings snapshot.
26    fn explain_settings(
27        &self,
28        control: &uqa_core::memory::ProductionControl<'_>,
29    ) -> Result<
30        uqa_core::memory::Produced<uqa_sql::semantics::parameters::explain::ExplainSettings>,
31        SQLError,
32    > {
33        let settings = self.parameter_settings();
34        uqa_sql::semantics::parameters::explain::capture(
35            &|definition, control| {
36                settings
37                    .iter()
38                    .find(|setting| setting.definition.name == definition.name)
39                    .map(|setting| control.copy_text(&setting.setting).map_err(Into::into))
40                    .transpose()
41            },
42            control,
43        )
44    }
45    fn prepared_statements(&self) -> Vec<PreparedStatementMetadata>;
46    fn cursors(&self) -> Vec<CursorMetadata>;
47}
48pub trait CatalogExpressionEvaluation: Sync {
49    fn evaluate(&self, expression: &Expr) -> Result<Value, SQLError>;
50}
51pub trait RelationCounts: Sync {
52    fn table_doc_count(&self, table: &str) -> Result<u64, SQLError>;
53}
54pub use uqa_sql::catalog::view::ViewMutationCapabilities;
55pub struct ViewCatalogMetadata {
56    pub catalog: ViewMutationCapabilities,
57    pub catalog_columns: Vec<bool>,
58    pub check_option: String,
59}
60pub trait ViewCatalogCapabilities: Sync {
61    fn view_updatability(&self, name: &str) -> Result<ViewCatalogMetadata, SQLError>;
62    fn has_instead_of_trigger(&self, name: &str, event: TriggerEvent) -> Result<bool, SQLError>;
63    fn view_updatability_with_catalog(
64        &self,
65        name: &str,
66        _catalog: &super::CatalogReadView,
67        _resolution: &RelationNameResolution,
68    ) -> Result<ViewCatalogMetadata, SQLError> {
69        self.view_updatability(name)
70    }
71    fn has_instead_of_trigger_with_catalog(
72        &self,
73        name: &str,
74        event: TriggerEvent,
75        _catalog: &super::CatalogReadView,
76        _resolution: &RelationNameResolution,
77    ) -> Result<bool, SQLError> {
78        self.has_instead_of_trigger(name, event)
79    }
80}
81
82pub trait CatalogNamespace: Sync {
83    fn current_schema_names(&self, include_implicit: bool) -> Result<Vec<String>, SQLError>;
84    /// Resolve visibility through a caller-selected catalog while preserving legacy namespace services.
85    fn current_schema_names_with_catalog(
86        &self,
87        _catalog: &super::CatalogReadView,
88        include_implicit: bool,
89    ) -> Result<Vec<String>, SQLError> {
90        self.current_schema_names(include_implicit)
91    }
92}
93
94pub trait CatalogSnapshotSource: Sync {
95    fn catalog_snapshot(&self) -> super::CatalogReadView;
96    /// 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.
97    fn builtin_routine_permissions(
98        &self,
99        current_role: RoleReference,
100    ) -> super::security::builtin_routines::execution::BuiltinRoutinePermissions {
101        super::security::builtin_routines::execution::BuiltinRoutinePermissions::new(
102            self.catalog_snapshot(),
103            current_role,
104        )
105    }
106    fn refreshed_catalog_snapshot(&self) -> Result<super::CatalogReadView, SQLError>;
107    /// Refresh definitions without capturing a query view that definition coordination will discard.
108    fn refresh_catalog(&self) -> Result<(), SQLError> {
109        self.refreshed_catalog_snapshot().map(|_| ())
110    }
111    /// Attach the original query participant without replacing the retained catalog or observing unused sources.
112    fn bind_query_reads(
113        &self,
114        snapshot: super::CatalogReadView,
115    ) -> Result<super::CatalogReadView, SQLError> {
116        Ok(snapshot)
117    }
118    /// Retain direct catalog rows independently of name binding and SSI attribution.
119    fn retain_catalog_rows(
120        &self,
121        snapshot: super::CatalogReadView,
122    ) -> Result<super::CatalogReadView, SQLError> {
123        Ok(snapshot)
124    }
125    /// Definition coordination uses the refreshed session catalog, independently from an ordinary query's retained snapshot.
126    fn current_catalog_snapshot(&self) -> super::CatalogReadView;
127    /// 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`.
128    fn current_catalog_revision(&self) -> Option<u64> {
129        None
130    }
131}
132impl CatalogSnapshotSource for super::CatalogReadView {
133    fn current_catalog_revision(&self) -> Option<u64> {
134        Some(0)
135    }
136    fn refresh_catalog(&self) -> Result<(), SQLError> {
137        Ok(())
138    }
139    fn current_catalog_snapshot(&self) -> super::CatalogReadView {
140        self.clone()
141    }
142    fn refreshed_catalog_snapshot(&self) -> Result<super::CatalogReadView, SQLError> {
143        Ok(self.clone())
144    }
145    fn catalog_snapshot(&self) -> super::CatalogReadView {
146        self.clone()
147    }
148}