Skip to main content

uqa_sql/semantics/
rules.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Rewrite-rule declaration and RETURNING contracts.
8
9use crate::{
10    ast::{RuleEvent, Statement},
11    catalog::events::StoredRule,
12    SQLError,
13};
14use uqa_core::memory::{Produced, ProductionControl};
15use uqa_core::RelationIdentity;
16
17/// Resolve stored rule definitions and a mutation's canonical target.
18pub trait RuleCatalog {
19    fn relation_has_rules(&self, table: &str) -> Result<bool, SQLError>;
20    fn resolve_rule_relation(&self, table: &str) -> Result<RelationIdentity, SQLError>;
21    fn rules_for(&self, table: &str, event: RuleEvent) -> Result<Vec<StoredRule>, SQLError>;
22    fn resolve_mutation_target(&self, name: &str, bound: bool) -> Result<String, SQLError>;
23
24    fn capture_rules(
25        &self,
26        table: &str,
27        event: RuleEvent,
28    ) -> Result<crate::catalog::events::selection::CapturedRules, SQLError> {
29        self.capture_rules_with_control(table, event, &ProductionControl::uncontrolled())
30    }
31
32    /// Capture active execution rules at the ordinary lookup boundary. Native catalogs retain the live immutable registry generation without copying its declarations.
33    fn capture_rules_with_control(
34        &self,
35        table: &str,
36        event: RuleEvent,
37        control: &ProductionControl<'_>,
38    ) -> Result<crate::catalog::events::selection::CapturedRules, SQLError> {
39        control.check()?;
40        crate::catalog::events::selection::CapturedRules::from_external(
41            self.rules_for(table, event)?,
42            control,
43        )
44    }
45
46    /// External catalogs may supply owned metadata. Native catalogs override this observation to lend the selected immutable rule declarations directly.
47    fn visit_rules_with_control(
48        &self,
49        table: &str,
50        event: RuleEvent,
51        reverse: bool,
52        control: &ProductionControl<'_>,
53        visit: &mut dyn FnMut(&StoredRule) -> Result<(), SQLError>,
54    ) -> Result<(), SQLError> {
55        control.check()?;
56        let rules = self.rules_for(table, event)?;
57        if reverse {
58            for rule in rules.iter().rev() {
59                control.check()?;
60                visit(rule)?;
61            }
62        } else {
63            for rule in &rules {
64                control.check()?;
65                visit(rule)?;
66            }
67        }
68        Ok(())
69    }
70
71    fn resolve_rule_relation_with_control(
72        &self,
73        table: &str,
74        control: &ProductionControl<'_>,
75    ) -> Result<Produced<RelationIdentity>, SQLError> {
76        control.check()?;
77        let relation = self.resolve_rule_relation(table)?;
78        production::copy_relation(&relation, control)
79    }
80
81    fn resolve_mutation_target_with_control(
82        &self,
83        name: &str,
84        bound: bool,
85        control: &ProductionControl<'_>,
86    ) -> Result<Produced<String>, SQLError> {
87        control.check()?;
88        Ok(control.copy_text(&self.resolve_mutation_target(name, bound)?)?)
89    }
90}
91
92pub mod binding;
93mod ctes;
94mod input_contract;
95mod production;
96pub use ctes::validate_rule_cte_contract;
97pub use input_contract::validate_insert_rule_query_contract;
98pub use production::{
99    validate_insert_rule_query_contract_with_control, validate_rule_cte_contract_with_control,
100    validate_rule_returning_contract_with_control,
101};
102pub fn validate_rule_returning_contract(
103    catalog: &dyn RuleCatalog,
104    table: &str,
105    event: RuleEvent,
106    requested: bool,
107) -> Result<(), SQLError> {
108    validate_rule_returning_contract_with_control(
109        catalog,
110        table,
111        event,
112        requested,
113        &ProductionControl::uncontrolled(),
114    )
115}
116
117const fn rule_event_name(event: RuleEvent) -> &'static str {
118    match event {
119        RuleEvent::Select => "SELECT",
120        RuleEvent::Insert => "INSERT",
121        RuleEvent::Update => "UPDATE",
122        RuleEvent::Delete => "DELETE",
123    }
124}
125
126pub fn statement_has_returning(statement: &Statement) -> bool {
127    match statement {
128        Statement::Insert(statement) => !statement.returning.is_empty(),
129        Statement::Update(statement) => !statement.returning.is_empty(),
130        Statement::Delete(statement) => !statement.returning.is_empty(),
131        _ => false,
132    }
133}
134
135pub fn clear_statement_returning(statement: &mut Statement) {
136    match statement {
137        Statement::Insert(statement) => statement.returning.clear(),
138        Statement::Update(statement) => statement.returning.clear(),
139        Statement::Delete(statement) => statement.returning.clear(),
140        _ => {}
141    }
142}
143
144pub mod action_binding;
145
146pub mod analysis;
147pub mod returning;
148
149pub mod insert_inputs;