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};
10mod production;
11pub use production::{
12    analysis_parameters_with_control, declared_parameter_types_for_plan_with_control,
13    declared_parameter_types_with_control,
14};
15pub mod arguments;
16pub mod composites;
17pub mod definition;
18pub mod dependencies;
19pub mod entry;
20pub mod ownership;
21pub mod planning;
22pub mod utility;
23
24pub fn declared_parameter_types(
25    resolver: &dyn crate::FunctionTypeResolver,
26    logical_plan: &mut crate::plan::UnifiedPlan,
27    declared: &[ColumnType],
28) -> Result<Vec<Option<ColumnType>>, SQLError> {
29    declared_parameter_types_with_control(
30        resolver,
31        logical_plan,
32        declared,
33        &uqa_core::memory::ProductionControl::uncontrolled(),
34    )?
35    .into_uncontrolled()
36    .map_err(|_| SQLError::Internal("ordinary prepared parameter owner".into()))
37}
38
39pub fn analyze_prepared_plan(
40    routines: &dyn crate::routines::RoutineResolution,
41    plan: &crate::plan::UnifiedPlan,
42    parameter_types: &[Option<ColumnType>],
43    scope: &crate::binding::context::BindingContext<'_>,
44) -> Result<Option<RowSchema>, SQLError> {
45    let params = analysis_parameters(parameter_types);
46    match plan {
47        crate::plan::UnifiedPlan::Query(query) => {
48            crate::binding::analyze_query_plan_schema(routines, query, &params, scope, None)
49                .map(Some)
50        }
51        crate::plan::UnifiedPlan::Command(command) => {
52            crate::binding::analyze_prepared_command_schema(routines, command, &params, scope)
53        }
54    }
55}
56
57pub(crate) fn analysis_parameters(parameter_types: &[Option<ColumnType>]) -> Vec<SQLParam> {
58    analysis_parameters_with_control(
59        parameter_types,
60        &uqa_core::memory::ProductionControl::uncontrolled(),
61    )
62    .expect("ordinary analysis parameters")
63    .into_uncontrolled()
64    .expect("ordinary parameter owner")
65}
66
67pub fn prepared_result_schema_matches(left: Option<&RowSchema>, right: Option<&RowSchema>) -> bool {
68    match (left, right) {
69        (None, None) => true,
70        (Some(left), Some(right)) => {
71            left.columns() == right.columns()
72                && left.column_types().len() == right.column_types().len()
73                && left
74                    .column_types()
75                    .iter()
76                    .zip(right.column_types())
77                    .all(|(left, right)| {
78                        prepared_type_identity(left.as_ref())
79                            == prepared_type_identity(right.as_ref())
80                    })
81        }
82        _ => false,
83    }
84}
85
86fn prepared_type_identity(ty: Option<&ColumnType>) -> Option<(u32, i32)> {
87    ty.map(|ty| {
88        if let ColumnType::Domain { oid, .. } = ty {
89            (*oid, -1)
90        } else {
91            let metadata = crate::catalog::result_type::postgres_result_type(ty);
92            (metadata.type_oid, metadata.type_modifier)
93        }
94    })
95}
96
97pub fn statement_error(sqlstate: &str, name: &str, reason: &str) -> SQLError {
98    error(sqlstate, format!("prepared statement \"{name}\" {reason}"))
99}
100
101pub fn execute_parameter_types(
102    name: &str,
103    types: Option<Vec<Option<ColumnType>>>,
104    argument_count: usize,
105) -> Result<Vec<Option<ColumnType>>, SQLError> {
106    let types = types.ok_or_else(|| statement_error("26000", name, "does not exist"))?;
107    // SQL EXECUTE ignores argument lists for parameterless definitions; protocol Bind checks its own arity.
108    if types.is_empty() {
109        return Ok(Vec::new());
110    }
111    if argument_count != types.len() {
112        return Err(error(
113            "42601",
114            format!("wrong number of parameters for prepared statement \"{name}\""),
115        ));
116    }
117    Ok(types)
118}
119
120/// Host binding checks every supplied parameter, including unused utility declarations.
121pub fn validate_host_parameter_count(
122    name: &str,
123    supplied: usize,
124    expected: usize,
125) -> Result<(), SQLError> {
126    if supplied == expected {
127        return Ok(());
128    }
129    Err(error(
130        "08P01",
131        format!("bind message supplies {supplied} parameters, but prepared statement \"{name}\" requires {expected}"),
132    ))
133}
134
135pub(super) fn error(sqlstate: &str, message: impl Into<String>) -> SQLError {
136    SQLError::Routine {
137        sqlstate: sqlstate.into(),
138        message: message.into(),
139    }
140}
141
142#[cfg(test)]
143mod tests;