Skip to main content

uqa_sql/
prepared.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Prepared definitions, result descriptors, and SQL EXECUTE argument contracts.
8
9use crate::{ColumnType, RowSchema, SQLError, SQLParam};
10use uqa_core::Value;
11pub mod arguments;
12pub mod composites;
13pub mod definition;
14pub mod dependencies;
15pub mod entry;
16pub mod planning;
17pub mod utility;
18
19pub fn declared_parameter_types(
20    resolver: &dyn crate::FunctionTypeResolver,
21    logical_plan: &mut crate::plan::UnifiedPlan,
22    declared: &[ColumnType],
23) -> Result<Vec<Option<ColumnType>>, SQLError> {
24    let mut parameter_types = declared
25        .iter()
26        .map(|ty| match ty {
27            crate::ast::ColumnType::Named(name) if is_unknown_type(name)? => Ok(None),
28            _ => crate::type_resolution::resolve_declared_column_type(resolver, ty).map(Some),
29        })
30        .collect::<Result<Vec<_>, _>>()?;
31    if utility::requires_analysis(logical_plan) {
32        logical_plan.rewrite_scalar_expressions(&mut |expression| {
33            if let crate::ScalarExpr::Param(index) = expression {
34                parameter_types.resize(parameter_types.len().max(*index), None);
35            }
36        });
37    }
38    Ok(parameter_types)
39}
40
41fn is_unknown_type(name: &str) -> Result<bool, crate::SQLError> {
42    Ok(crate::parse_regtype_name(name)?.is_some_and(|parsed| {
43        parsed.array_dimensions == 0
44            && !parsed.has_type_modifiers
45            && match parsed.names.as_slice() {
46                [local] => local == "unknown",
47                [schema, local] => schema == "pg_catalog" && local == "unknown",
48                _ => false,
49            }
50    }))
51}
52
53pub fn analyze_prepared_plan(
54    routines: &dyn crate::routines::RoutineResolution,
55    plan: &crate::plan::UnifiedPlan,
56    parameter_types: &[Option<ColumnType>],
57    scope: &crate::binding::context::BindingContext<'_>,
58) -> Result<Option<RowSchema>, SQLError> {
59    let params = analysis_parameters(parameter_types);
60    match plan {
61        crate::plan::UnifiedPlan::Query(query) => {
62            crate::binding::analyze_query_plan_schema(routines, query, &params, scope, None)
63                .map(Some)
64        }
65        crate::plan::UnifiedPlan::Command(command) => {
66            crate::binding::analyze_prepared_command_schema(routines, command, &params, scope)
67        }
68    }
69}
70
71pub(crate) fn analysis_parameters(parameter_types: &[Option<ColumnType>]) -> Vec<SQLParam> {
72    parameter_types
73        .iter()
74        .map(|ty| match ty {
75            Some(ty) => SQLParam::typed_scalar(Value::Null, ty.clone()),
76            None => SQLParam::Scalar(Value::Null),
77        })
78        .collect()
79}
80
81pub fn prepared_result_schema_matches(left: Option<&RowSchema>, right: Option<&RowSchema>) -> bool {
82    match (left, right) {
83        (None, None) => true,
84        (Some(left), Some(right)) => {
85            left.columns() == right.columns()
86                && left.column_types().len() == right.column_types().len()
87                && left
88                    .column_types()
89                    .iter()
90                    .zip(right.column_types())
91                    .all(|(left, right)| {
92                        prepared_type_identity(left.as_ref())
93                            == prepared_type_identity(right.as_ref())
94                    })
95        }
96        _ => false,
97    }
98}
99
100fn prepared_type_identity(ty: Option<&ColumnType>) -> Option<(u32, i32)> {
101    ty.map(|ty| {
102        if let ColumnType::Domain { oid, .. } = ty {
103            (*oid, -1)
104        } else {
105            let metadata = crate::catalog::result_type::postgres_result_type(ty);
106            (metadata.type_oid, metadata.type_modifier)
107        }
108    })
109}
110
111pub fn statement_error(sqlstate: &str, name: &str, reason: &str) -> SQLError {
112    error(sqlstate, format!("prepared statement \"{name}\" {reason}"))
113}
114
115pub fn execute_parameter_types(
116    name: &str,
117    types: Option<Vec<Option<ColumnType>>>,
118    argument_count: usize,
119) -> Result<Vec<Option<ColumnType>>, SQLError> {
120    let types = types.ok_or_else(|| statement_error("26000", name, "does not exist"))?;
121    // SQL EXECUTE ignores argument lists for parameterless definitions; protocol Bind checks its own arity.
122    if types.is_empty() {
123        return Ok(Vec::new());
124    }
125    if argument_count != types.len() {
126        return Err(error(
127            "42601",
128            format!("wrong number of parameters for prepared statement \"{name}\""),
129        ));
130    }
131    Ok(types)
132}
133
134/// Host binding checks every supplied parameter, including unused utility declarations.
135pub fn validate_host_parameter_count(
136    name: &str,
137    supplied: usize,
138    expected: usize,
139) -> Result<(), SQLError> {
140    if supplied == expected {
141        return Ok(());
142    }
143    Err(error(
144        "08P01",
145        format!("bind message supplies {supplied} parameters, but prepared statement \"{name}\" requires {expected}"),
146    ))
147}
148
149pub(super) fn error(sqlstate: &str, message: impl Into<String>) -> SQLError {
150    SQLError::Routine {
151        sqlstate: sqlstate.into(),
152        message: message.into(),
153    }
154}
155
156#[cfg(test)]
157mod tests;