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::RelationIdentity;
15
16/// Resolve stored rule definitions and a mutation's canonical target.
17pub trait RuleCatalog {
18    fn relation_has_rules(&self, table: &str) -> Result<bool, SQLError>;
19    fn resolve_rule_relation(&self, table: &str) -> Result<RelationIdentity, SQLError>;
20    fn rules_for(&self, table: &str, event: RuleEvent) -> Result<Vec<StoredRule>, SQLError>;
21    fn resolve_mutation_target(&self, name: &str, bound: bool) -> Result<String, SQLError>;
22}
23
24pub mod binding;
25mod ctes;
26mod input_contract;
27pub use ctes::validate_rule_cte_contract;
28pub use input_contract::validate_insert_rule_query_contract;
29pub fn validate_rule_returning_contract(
30    catalog: &dyn RuleCatalog,
31    table: &str,
32    event: RuleEvent,
33    requested: bool,
34) -> Result<(), SQLError> {
35    if !requested {
36        return Ok(());
37    }
38    let table = catalog.resolve_rule_relation(table)?.qualified_name();
39    let rules = catalog.rules_for(&table, event)?;
40    if rules.is_empty() || !rules.iter().any(|rule| rule.definition.instead) {
41        return Ok(());
42    }
43    let providers = rules
44        .iter()
45        .flat_map(|rule| &rule.definition.actions)
46        .filter(|action| statement_has_returning(action))
47        .count();
48    if providers > 1 {
49        return Err(SQLError::Routine {
50            sqlstate: "0A000".into(),
51            message: "cannot have RETURNING lists in multiple rules".into(),
52        });
53    }
54    if providers == 1 {
55        return Ok(());
56    }
57    let relation = RelationIdentity::from_legacy_name(&table)
58        .map_err(|error| SQLError::Internal(format!("decode rule relation `{table}`: {error}")))?;
59    let event = rule_event_name(event);
60    Err(SQLError::Diagnostic {
61        sqlstate: "0A000".into(),
62        message: format!(
63            "cannot perform {event} RETURNING on relation \"{}\"",
64            relation.name
65        ),
66        detail: None,
67        hint: Some(format!(
68            "You need an unconditional ON {event} DO INSTEAD rule with a RETURNING clause."
69        )),
70    })
71}
72
73const fn rule_event_name(event: RuleEvent) -> &'static str {
74    match event {
75        RuleEvent::Select => "SELECT",
76        RuleEvent::Insert => "INSERT",
77        RuleEvent::Update => "UPDATE",
78        RuleEvent::Delete => "DELETE",
79    }
80}
81
82pub fn statement_has_returning(statement: &Statement) -> bool {
83    match statement {
84        Statement::Insert(statement) => !statement.returning.is_empty(),
85        Statement::Update(statement) => !statement.returning.is_empty(),
86        Statement::Delete(statement) => !statement.returning.is_empty(),
87        _ => false,
88    }
89}
90
91pub fn clear_statement_returning(statement: &mut Statement) {
92    match statement {
93        Statement::Insert(statement) => statement.returning.clear(),
94        Statement::Update(statement) => statement.returning.clear(),
95        Statement::Delete(statement) => statement.returning.clear(),
96        _ => {}
97    }
98}
99
100pub mod action_binding;
101
102pub mod analysis;
103pub mod returning;
104
105pub mod insert_inputs;