Skip to main content

uqa_sql/plpgsql/
variable_conflicts.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Variable references of embedded statements resolved as `PostgreSQL`'s parser hooks for `PL/pgSQL` resolve them: a name that a variable takes is checked against the columns and relations the statement can see there, and a name that both take is ambiguous unless `plpgsql.variable_conflict` chooses one.
8//!
9//! Binding a statement replaces each variable reference with the variable's value. To learn how each reference resolves, the statement is first bound with every reference replaced by a positional parameter numbered after the reference, which the binder resolves in the statement's own scopes, and then bound again leaving to the statement each name that resolves elsewhere. Both bindings walk the statement in the same order, so the numbers identify the references without relating the statement's syntax to its lowered plan.
10
11use super::binding::{bind_expr, bind_statement, ResolvedVariable, VariableResolver};
12use super::options::VariableConflict;
13use super::{Expr, Projection, Result, SelectStmt, Statement};
14use crate::ast::InternalColumnRef;
15use crate::binding::VariableSiteResolution;
16use crate::{SQLError, SQLParam, ScalarExpr};
17use uqa_core::Value;
18
19/// A variable reference of a statement: the name as written, and the value the function's resolver binds it to.
20struct VariableSite {
21    reference: Expr,
22    binding: Expr,
23}
24
25/// Resolve how the variable sites of a statement resolve in it: the statement with each site as the positional parameter numbered after it, the sites' values as typed parameters, and the sites' names as written.
26pub type VariableSiteResolver<'a> =
27    &'a mut dyn FnMut(
28        Statement,
29        Vec<SQLParam>,
30        Vec<ScalarExpr>,
31    ) -> std::result::Result<Vec<VariableSiteResolution>, SQLError>;
32
33/// Number each variable reference the inner resolver binds and stand a positional parameter in for it.
34struct VariableSiteMarker<'a> {
35    inner: &'a mut dyn VariableResolver,
36    sites: Vec<VariableSite>,
37}
38
39impl VariableSiteMarker<'_> {
40    fn mark(&mut self, reference: Expr, binding: Option<Expr>) -> Option<Expr> {
41        let binding = binding?;
42        self.sites.push(VariableSite { reference, binding });
43        Some(Expr::Param(self.sites.len()))
44    }
45}
46
47impl VariableResolver for VariableSiteMarker<'_> {
48    fn resolve_name(&mut self, name: &str) -> Result<Option<ResolvedVariable>> {
49        self.inner.resolve_name(name)
50    }
51
52    fn resolve_qualified(
53        &mut self,
54        qualifier: &str,
55        column: &str,
56    ) -> Result<Option<ResolvedVariable>> {
57        self.inner.resolve_qualified(qualifier, column)
58    }
59
60    fn resolve_param(&mut self, index: usize) -> Result<Option<ResolvedVariable>> {
61        self.inner.resolve_param(index)
62    }
63
64    fn rewrite_name(&mut self, name: &str) -> Result<Option<Expr>> {
65        let binding = self.inner.rewrite_name(name)?;
66        Ok(self.mark(Expr::Column(name.to_string().into()), binding))
67    }
68
69    fn rewrite_qualified(&mut self, qualifier: &str, column: &str) -> Result<Option<Expr>> {
70        let binding = self.inner.rewrite_qualified(qualifier, column)?;
71        Ok(self.mark(
72            Expr::QualifiedColumn {
73                qualifier: qualifier.to_string(),
74                column: column.to_string().into(),
75            },
76            binding,
77        ))
78    }
79
80    fn rewrite_qualified_star(&mut self, qualifier: &str) -> Result<Option<Vec<Expr>>> {
81        self.inner.rewrite_qualified_star(qualifier)
82    }
83
84    fn rewrite_qualified_whole_row(&mut self, qualifier: &str) -> Result<Option<Expr>> {
85        self.inner.rewrite_qualified_whole_row(qualifier)
86    }
87
88    fn rewrite_param(&mut self, index: usize) -> Result<Option<Expr>> {
89        self.inner.rewrite_param(index)
90    }
91
92    fn rewrite_internal(&mut self, column: InternalColumnRef) -> Result<Option<Expr>> {
93        self.inner.rewrite_internal(column)
94    }
95}
96
97/// Bind the variable references the inner resolver binds, except those whose site `keep` marks, whose names the statement resolves.
98struct VariableSiteFilter<'a> {
99    inner: &'a mut dyn VariableResolver,
100    keep: &'a [bool],
101    next: usize,
102}
103
104impl VariableSiteFilter<'_> {
105    fn filter(&mut self, binding: Option<Expr>) -> Option<Expr> {
106        let binding = binding?;
107        let site = self.next;
108        self.next += 1;
109        (!self.keep.get(site).copied().unwrap_or(false)).then_some(binding)
110    }
111}
112
113impl VariableResolver for VariableSiteFilter<'_> {
114    fn resolve_name(&mut self, name: &str) -> Result<Option<ResolvedVariable>> {
115        self.inner.resolve_name(name)
116    }
117
118    fn resolve_qualified(
119        &mut self,
120        qualifier: &str,
121        column: &str,
122    ) -> Result<Option<ResolvedVariable>> {
123        self.inner.resolve_qualified(qualifier, column)
124    }
125
126    fn resolve_param(&mut self, index: usize) -> Result<Option<ResolvedVariable>> {
127        self.inner.resolve_param(index)
128    }
129
130    fn rewrite_name(&mut self, name: &str) -> Result<Option<Expr>> {
131        let binding = self.inner.rewrite_name(name)?;
132        Ok(self.filter(binding))
133    }
134
135    fn rewrite_qualified(&mut self, qualifier: &str, column: &str) -> Result<Option<Expr>> {
136        let binding = self.inner.rewrite_qualified(qualifier, column)?;
137        Ok(self.filter(binding))
138    }
139
140    fn rewrite_qualified_star(&mut self, qualifier: &str) -> Result<Option<Vec<Expr>>> {
141        self.inner.rewrite_qualified_star(qualifier)
142    }
143
144    fn rewrite_qualified_whole_row(&mut self, qualifier: &str) -> Result<Option<Expr>> {
145        self.inner.rewrite_qualified_whole_row(qualifier)
146    }
147
148    fn rewrite_param(&mut self, index: usize) -> Result<Option<Expr>> {
149        self.inner.rewrite_param(index)
150    }
151
152    fn rewrite_internal(&mut self, column: InternalColumnRef) -> Result<Option<Expr>> {
153        self.inner.rewrite_internal(column)
154    }
155}
156
157/// The error `plpgsql_post_column_ref` raises for a name that a variable and a column or relation both take under `plpgsql.variable_conflict = error`.
158fn ambiguous_variable_error(reference: &Expr) -> SQLError {
159    let name = match reference {
160        Expr::QualifiedColumn { qualifier, column } => format!("{qualifier}.{column}"),
161        Expr::Column(name) => name.to_string(),
162        other => format!("{other:?}"),
163    };
164    SQLError::Diagnostic {
165        sqlstate: "42702".into(),
166        message: format!("column reference \"{name}\" is ambiguous"),
167        detail: Some("It could refer to either a PL/pgSQL variable or a table column.".into()),
168        hint: None,
169    }
170}
171
172/// The typed parameter that stands for a site's value while the binder resolves the statement.
173pub(super) fn site_parameter(binding: &Expr, resolver: &dyn VariableResolver) -> Result<SQLParam> {
174    Ok(match binding {
175        Expr::TypedLiteral { value, ty, .. } => resolver.parameter_type(ty).map_or_else(
176            || SQLParam::scalar(value.clone()),
177            |ty| SQLParam::typed_scalar(value.clone(), ty),
178        ),
179        Expr::Literal(value) => SQLParam::scalar(value.clone()),
180        Expr::RetainedLiteral(literal) => return site_parameter(&literal.materialize()?, resolver),
181        _ => SQLParam::scalar(Value::Null),
182    })
183}
184
185/// The name a site is written with, as the binder reads it.
186fn site_name(reference: &Expr) -> ScalarExpr {
187    match reference {
188        Expr::QualifiedColumn { qualifier, column } => ScalarExpr::QualifiedColumn {
189            qualifier: qualifier.clone(),
190            column: column.clone(),
191        },
192        Expr::Column(name) => ScalarExpr::Column(name.clone()),
193        _ => ScalarExpr::Literal(Value::Null),
194    }
195}
196
197/// Which sites keep their names: those an output column takes, and those a column takes when `conflict` chooses the column. A site a column takes under `error` fails the statement.
198fn kept_names(
199    sites: &[VariableSite],
200    resolutions: &[VariableSiteResolution],
201    conflict: VariableConflict,
202) -> std::result::Result<Vec<bool>, SQLError> {
203    sites
204        .iter()
205        .zip(resolutions)
206        .map(|(site, resolution)| match (resolution, conflict) {
207            (VariableSiteResolution::Output, _)
208            | (VariableSiteResolution::Column, VariableConflict::UseColumn) => Ok(true),
209            (VariableSiteResolution::Column, VariableConflict::Error) => {
210                Err(ambiguous_variable_error(&site.reference))
211            }
212            (VariableSiteResolution::Column, VariableConflict::UseVariable)
213            | (VariableSiteResolution::Variable, _) => Ok(false),
214        })
215        .collect()
216}
217
218/// Bind the variables of an embedded statement, resolving each name that a variable takes against the columns and relations the statement can see as `conflict` directs.
219pub fn bind_statement_variables(
220    statement: &Statement,
221    resolver: &mut dyn VariableResolver,
222    conflict: VariableConflict,
223    resolve_sites: VariableSiteResolver<'_>,
224) -> Result<Statement> {
225    let keep = statement_variable_names(statement, resolver, conflict, resolve_sites)?;
226    bind_statement(
227        statement,
228        &mut VariableSiteFilter {
229            inner: resolver,
230            keep: &keep,
231            next: 0,
232        },
233    )
234}
235
236/// Resolve names without retaining invocation values in the compiled syntax.
237pub(super) fn statement_variable_names(
238    statement: &Statement,
239    resolver: &mut dyn VariableResolver,
240    conflict: VariableConflict,
241    resolve_sites: VariableSiteResolver<'_>,
242) -> Result<Vec<bool>> {
243    let mut numbering = VariableSiteMarker {
244        inner: resolver,
245        sites: Vec::new(),
246    };
247    let numbered = bind_statement(statement, &mut numbering)?;
248    let sites = numbering.sites;
249    if sites.is_empty() {
250        return Ok(Vec::new());
251    }
252    let resolutions = resolve_sites(
253        numbered,
254        sites
255            .iter()
256            .map(|site| site_parameter(&site.binding, resolver))
257            .collect::<Result<_>>()?,
258        sites
259            .iter()
260            .map(|site| site_name(&site.reference))
261            .collect(),
262    )?;
263    kept_names(&sites, &resolutions, conflict)
264}
265
266/// Bind the variables of an embedded expression, which `PostgreSQL` analyzes as `SELECT expression`: only a subquery lets a name of the expression meet a column, so an expression without one binds every variable it names.
267pub fn bind_expression_variables(
268    expression: &Expr,
269    resolver: &mut dyn VariableResolver,
270    conflict: VariableConflict,
271    resolve_sites: VariableSiteResolver<'_>,
272) -> Result<Expr> {
273    let queries = expression.any_node(&|node| {
274        matches!(
275            node,
276            Expr::ScalarSubquery(_) | Expr::Exists { .. } | Expr::InSubquery { .. }
277        )
278    });
279    if !queries {
280        return bind_expr(expression, resolver);
281    }
282    let mut numbering = VariableSiteMarker {
283        inner: resolver,
284        sites: Vec::new(),
285    };
286    let numbered = bind_expr(expression, &mut numbering)?;
287    let sites = numbering.sites;
288    if sites.is_empty() {
289        return Ok(numbered);
290    }
291    let resolutions = resolve_sites(
292        expression_query(numbered),
293        sites
294            .iter()
295            .map(|site| site_parameter(&site.binding, resolver))
296            .collect::<Result<_>>()?,
297        sites
298            .iter()
299            .map(|site| site_name(&site.reference))
300            .collect(),
301    )?;
302    let keep = kept_names(&sites, &resolutions, conflict)?;
303    bind_expr(
304        expression,
305        &mut VariableSiteFilter {
306            inner: resolver,
307            keep: &keep,
308            next: 0,
309        },
310    )
311}
312
313/// `SELECT expression`, the query `PostgreSQL` analyzes for an embedded expression.
314pub(crate) fn expression_query(expression: Expr) -> Statement {
315    Statement::Select(Box::new(SelectStmt {
316        windows: Vec::new(),
317        projections: vec![Projection {
318            expr: expression,
319            alias: None,
320        }],
321        values: Vec::new(),
322        from: None,
323        r#where: None,
324        group_by: Vec::new(),
325        grouping_sets: Vec::new(),
326        group_distinct: false,
327        having: None,
328        order_by: Vec::new(),
329        limit: None,
330        with_ties: false,
331        offset: None,
332        with: Vec::new(),
333        set_op: None,
334        distinct: false,
335        distinct_on: Vec::new(),
336        locking: Vec::new(),
337    }))
338}