Skip to main content

uqa_sql/routines/
compilation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Routine language validation and body lowering over declared types and fresh binding inputs.
8
9use super::{
10    declaration::{
11        resolve_plpgsql_datum_types, routine_definition_error, routine_parameter_regrole_constants,
12        validate_routine_declaration, RoutineTypeCatalog,
13    },
14    merge_columns::StoredMergeColumnCatalog,
15    CompiledFunctionBody, RoutineResolution,
16};
17use crate::{
18    ast::{ColumnType, CreateFunction, FunctionBody, FunctionReturns, Statement},
19    binding::{
20        snapshot::BindingSnapshot,
21        stored_relations::{
22            self, StoredQueryBindingContext, StoredQueryNamespace, StoredQuerySequences,
23            StoredRelationCatalog,
24        },
25    },
26    catalog::{
27        regrole_dependencies::{StoredRegroleConstants, StoredRegroleResolver},
28        resolution::RelationLookupMode,
29    },
30    plan::UnifiedPlan,
31    plpgsql::PlpgsqlCatalog,
32    type_resolution::canonical_routine_type_name,
33    SQLError, ScalarExpr,
34};
35
36pub trait RoutineParserCatalog {
37    fn plpgsql_catalog(&self) -> Result<PlpgsqlCatalog, SQLError>;
38    fn parser_settings(&self) -> crate::parser::ParserSettings {
39        crate::parser::ParserSettings::default()
40    }
41    fn parser_notice(&self, _notice: crate::SQLNotice) {}
42}
43pub trait RoutineCompilationCatalog: crate::schema::dependencies::oid_alias::OidAliasInput {
44    fn has_registered_aggregate_function(&self, name: &str) -> bool;
45    fn binding_snapshot(&self) -> Result<BindingSnapshot, SQLError>;
46    fn stored_query_namespace(&self) -> StoredQueryNamespace;
47}
48#[derive(Clone, Copy)]
49pub struct RoutineCompilationContext<'a> {
50    pub types: &'a dyn RoutineTypeCatalog,
51    pub parsers: &'a dyn RoutineParserCatalog,
52    pub catalog: &'a dyn RoutineCompilationCatalog,
53    pub routines: &'a dyn RoutineResolution,
54    pub relations: &'a dyn StoredRelationCatalog,
55    pub sequences: &'a dyn StoredQuerySequences,
56    pub merge: &'a dyn StoredMergeColumnCatalog,
57    pub regroles: &'a dyn StoredRegroleResolver,
58}
59
60pub fn compile_function_body(
61    context: &RoutineCompilationContext<'_>,
62    def: &CreateFunction,
63) -> Result<CompiledFunctionBody, SQLError> {
64    compile_function_body_inner(
65        context,
66        def,
67        false,
68        crate::plpgsql::PLpgSQLCompileMode::Validate,
69    )
70}
71
72/// Compile executable procedural structure without validating unreached SQL fragments.
73pub fn compile_function_body_for_execution(
74    context: &RoutineCompilationContext<'_>,
75    def: &CreateFunction,
76) -> Result<CompiledFunctionBody, SQLError> {
77    compile_function_body_inner(
78        context,
79        def,
80        false,
81        crate::plpgsql::PLpgSQLCompileMode::Runtime,
82    )
83}
84
85pub fn compile_persisted_function_body(
86    context: &RoutineCompilationContext<'_>,
87    def: &CreateFunction,
88) -> Result<CompiledFunctionBody, SQLError> {
89    compile_function_body_inner(
90        context,
91        def,
92        true,
93        crate::plpgsql::PLpgSQLCompileMode::Validate,
94    )
95}
96
97/// The body `CREATE FUNCTION` compiles under `check_function_bodies = off`: the declaration is checked as always, a SQL-standard body, which the statement itself analyzes, is compiled, and a body given as a string is left unexamined, `None`, for each session to compile when it first calls the routine.
98pub fn defer_function_body(
99    context: &RoutineCompilationContext<'_>,
100    def: &CreateFunction,
101) -> Result<Option<CompiledFunctionBody>, SQLError> {
102    if matches!(def.body, FunctionBody::Statements(_)) {
103        return compile_function_body(context, def).map(Some);
104    }
105    validate_routine_signature(context, def)?.reject_with(context.regroles)?;
106    Ok(None)
107}
108
109/// The checks `CREATE FUNCTION` makes whatever `check_function_bodies` says: the language and the body form it accepts, the declared types, and the role constants of parameter defaults, which are returned for the body's own checks.
110pub(super) fn validate_routine_signature(
111    context: &RoutineCompilationContext<'_>,
112    def: &CreateFunction,
113) -> Result<StoredRegroleConstants, SQLError> {
114    if !matches!(def.language.as_str(), "plpgsql" | "sql") {
115        return Err(SQLError::Routine {
116            sqlstate: "42704".into(),
117            message: format!("language \"{}\" does not exist", def.language),
118        });
119    }
120    if def.language == "plpgsql" && matches!(def.body, FunctionBody::Statements(_)) {
121        return Err(routine_definition_error(
122            "inline SQL function body only valid for language SQL",
123        ));
124    }
125    let stored_regrole_constants = routine_parameter_regrole_constants(context.types, def);
126    stored_regrole_constants.validate_inputs_with(context.regroles)?;
127    validate_routine_declaration(def)?;
128    Ok(stored_regrole_constants)
129}
130
131/// PL/pgSQL's compiler rejects declared arguments of a trigger function, which reads its arguments from `TG_ARGV`.
132fn reject_trigger_function_arguments(def: &CreateFunction) -> Result<(), SQLError> {
133    let returns_trigger = matches!(
134        &def.returns,
135        FunctionReturns::Scalar { type_name } if canonical_routine_type_name(type_name) == "trigger"
136    );
137    if returns_trigger && def.identity_arity() != 0 {
138        return Err(SQLError::Diagnostic {
139            sqlstate: "42P13".into(),
140            message: "trigger functions cannot have declared arguments".into(),
141            detail: None,
142            hint: Some(
143                "The arguments of the trigger can be accessed through TG_NARGS and TG_ARGV instead."
144                    .into(),
145            ),
146        });
147    }
148    Ok(())
149}
150
151fn compile_function_body_inner(
152    context: &RoutineCompilationContext<'_>,
153    def: &CreateFunction,
154    persisted_definition: bool,
155    mode: crate::plpgsql::PLpgSQLCompileMode,
156) -> Result<CompiledFunctionBody, SQLError> {
157    with_parser_context(context.parsers, || {
158        compile_body(context, def, persisted_definition, mode)
159    })
160}
161
162/// Read live lexical settings only after the routine's own configuration has been applied, and deliver parser notices even if compilation fails.
163pub fn with_parser_context<T>(
164    parsers: &dyn RoutineParserCatalog,
165    compile: impl FnOnce() -> Result<T, SQLError>,
166) -> Result<T, SQLError> {
167    let (result, metadata) = crate::parser::with_settings(parsers.parser_settings(), compile);
168    for notice in metadata.notices.iter() {
169        parsers.parser_notice(notice.clone());
170    }
171    result
172}
173
174fn compile_body(
175    context: &RoutineCompilationContext<'_>,
176    def: &CreateFunction,
177    persisted_definition: bool,
178    mode: crate::plpgsql::PLpgSQLCompileMode,
179) -> Result<CompiledFunctionBody, SQLError> {
180    let mut stored_regrole_constants = validate_routine_signature(context, def)?;
181    match def.language.as_str() {
182        "plpgsql" => {
183            stored_regrole_constants.reject_with(context.regroles)?;
184            reject_trigger_function_arguments(def)?;
185            let catalog = context.parsers.plpgsql_catalog()?;
186            let mut function =
187                crate::plpgsql::parse_function_with_catalog_mode(def, &catalog, mode)?;
188            resolve_plpgsql_datum_types(context.types, &mut function)?;
189            Ok(CompiledFunctionBody::PLpgSQL(function))
190        }
191        "sql" => {
192            let (statements, bind_catalog_dependencies) = match &def.body {
193                FunctionBody::Source(source) => {
194                    stored_regrole_constants.reject_with(context.regroles)?;
195                    (
196                        crate::compile(source).map_err(|error| def.source_body_error(error))?,
197                        false,
198                    )
199                }
200                FunctionBody::Statements(statements) => (statements.clone(), true),
201            };
202            let mut plans = compile_sql_routine_plans(
203                context,
204                def,
205                statements,
206                bind_catalog_dependencies,
207                persisted_definition && matches!(def.body, FunctionBody::Statements(_)),
208            )?;
209            if bind_catalog_dependencies {
210                for plan in &mut plans {
211                    stored_regrole_constants.collect_plan(plan);
212                }
213                stored_regrole_constants.reject_with(context.regroles)?;
214            }
215            Ok(CompiledFunctionBody::SQL(plans))
216        }
217        _ => unreachable!("routine language was validated above"),
218    }
219}
220
221fn compile_sql_routine_plans(
222    context: &RoutineCompilationContext<'_>,
223    def: &CreateFunction,
224    statements: Vec<Statement>,
225    bind_catalog_dependencies: bool,
226    persisted_definition: bool,
227) -> Result<Vec<UnifiedPlan>, SQLError> {
228    let positional_parameters =
229        super::body_validation::routine_parameter_values(context.types, def);
230    let parameters = super::body_parameters::sql_body_parameter_scope(def, &positional_parameters)?;
231    statements
232        .into_iter()
233        .map(|statement| {
234            let mut plan = lower_sql_routine_statement(
235                context,
236                statement,
237                SQLRoutineLowering {
238                    bind_catalog_dependencies,
239                    persisted_definition,
240                    preserve_target_expressions: false,
241                },
242            )?;
243            // A SQL-standard body keeps definition-time names. Source syntax
244            // stays unbound so statement reanalysis can use the current path;
245            // successful first-use analysis retains its own type identities.
246            if bind_catalog_dependencies {
247                let binding = context.catalog.binding_snapshot()?;
248                crate::binding::bind_routine_parameter_references(
249                    context.routines,
250                    &mut plan,
251                    &positional_parameters,
252                    &binding.context(),
253                    &parameters,
254                )?;
255                if let UnifiedPlan::Query(query) = &mut plan {
256                    crate::binding::bind_query_plan_routines_for_storage(
257                        context.routines,
258                        query,
259                        &positional_parameters,
260                        &binding.context(),
261                        None,
262                    )?;
263                }
264            }
265            // Stored definitions retain their analyzed logical expressions;
266            // immutable evaluation belongs to invocation planning.
267            Ok(plan)
268        })
269        .collect()
270}
271
272/// How a SQL routine statement is lowered from its stored syntax.
273#[derive(Clone, Copy)]
274pub struct SQLRoutineLowering {
275    /// Bind relations, sequences and `MERGE` target columns of catalog-owned syntax.
276    pub bind_catalog_dependencies: bool,
277    /// The syntax comes from a persisted definition, whose legacy call markers are upgraded.
278    pub persisted_definition: bool,
279    /// Keep `MERGE` target columns as written.
280    pub preserve_target_expressions: bool,
281}
282
283/// Lower one statement of a SQL routine body with its relations bound, before routine calls are bound.
284pub fn lower_sql_routine_statement(
285    context: &RoutineCompilationContext<'_>,
286    mut statement: Statement,
287    lowering: SQLRoutineLowering,
288) -> Result<UnifiedPlan, SQLError> {
289    if lowering.bind_catalog_dependencies {
290        validate_sql_standard_statement(&statement)?;
291    }
292    if lowering.bind_catalog_dependencies && !lowering.preserve_target_expressions {
293        super::merge_columns::normalize_stored_merge_target_columns(context.merge, &mut statement)?;
294    }
295    let mut plan = UnifiedPlan::lower_with(statement, &|name: &str| {
296        context.catalog.has_registered_aggregate_function(name)
297    });
298    if lowering.persisted_definition {
299        plan.rewrite_scalar_expressions(&mut |expression| {
300            let ScalarExpr::Func {
301                name,
302                binding,
303                args,
304                ..
305            } = expression
306            else {
307                return;
308            };
309            crate::ast::FunctionBinding::upgrade_legacy_serialized_dispatch(name, binding);
310            crate::ast::FunctionBinding::upgrade_legacy_array_slices(
311                binding,
312                args.len(),
313                |index| matches!(args[index], ScalarExpr::Literal(uqa_core::Value::Null)),
314            );
315        });
316    }
317    if lowering.bind_catalog_dependencies {
318        match &mut plan {
319            UnifiedPlan::Query(query) => {
320                let namespace = context.catalog.stored_query_namespace();
321                stored_relations::bind_stored_query_relations(
322                    &StoredQueryBindingContext {
323                        relations: context.relations,
324                        lookup_mode: if lowering.persisted_definition {
325                            RelationLookupMode::Bound
326                        } else {
327                            RelationLookupMode::Dynamic
328                        },
329                        sequences: context.sequences,
330                        temporary_schema: &namespace.temporary_schema,
331                        transition_relations: &namespace.transition_relations,
332                    },
333                    query,
334                    "SQL routine body",
335                    false,
336                    lowering.persisted_definition,
337                )?;
338            }
339            UnifiedPlan::Command(_) => {
340                crate::binding::stored_routines::mark_catalog_statement_relations_bound(&mut plan)?;
341            }
342        }
343    }
344    Ok(plan)
345}
346
347/// SQL-standard bodies retain analyzed queries and DML, never utility commands. Use the same command name as ordinary SQL diagnostics.
348pub(super) fn validate_sql_standard_statement(statement: &Statement) -> Result<(), SQLError> {
349    match sql_standard_utility(statement) {
350        Some(command) => Err(sql_standard_utility_error(&command)),
351        None => Ok(()),
352    }
353}
354
355fn sql_standard_utility(statement: &Statement) -> Option<Box<crate::plan::CommandPlan>> {
356    match statement {
357        Statement::Select(_)
358        | Statement::Values { .. }
359        | Statement::Insert(_)
360        | Statement::Update(_)
361        | Statement::Delete(_)
362        | Statement::Merge(_) => None,
363        _ => match UnifiedPlan::lower(statement.clone()) {
364            UnifiedPlan::Command(command) => Some(command),
365            UnifiedPlan::Query(_) => None,
366        },
367    }
368}
369
370fn sql_standard_utility_error(command: &crate::plan::CommandPlan) -> SQLError {
371    SQLError::Unsupported(format!(
372        "{} is not yet supported in unquoted SQL function body",
373        crate::result::completion::command_tag_name(command)
374    ))
375}
376
377/// `PostgreSQL` transforms the query inputs of CTAS, EXPLAIN and cursors, and resolves CALL, before rejecting the resulting utility. Other utility targets remain unexamined.
378pub(super) fn validate_sql_standard_statement_inputs(
379    context: &RoutineCompilationContext<'_>,
380    overloads: &super::resolution::RoutineOverloadContext<'_>,
381    statement: &Statement,
382    params: &[crate::SQLParam],
383    parameters: &crate::binding::RoutineParameterScope,
384) -> Result<(), SQLError> {
385    use crate::plan::CommandPlan;
386    let Some(command) = sql_standard_utility(statement) else {
387        return Ok(());
388    };
389    let error = sql_standard_utility_error(&command);
390    let plan = match *command {
391        CommandPlan::Explain { body, .. } => *body,
392        CommandPlan::CreateTableAs { query, .. }
393        | CommandPlan::CreateMaterializedView { query, .. }
394        | CommandPlan::DeclareCursor { query, .. } => UnifiedPlan::Query(query),
395        command @ CommandPlan::Call { .. } => UnifiedPlan::Command(Box::new(command)),
396        _ => return Err(error),
397    };
398    analyze_sql_standard_utility_input(context, overloads, plan, params, parameters)?;
399    Err(error)
400}
401
402fn analyze_sql_standard_utility_input(
403    context: &RoutineCompilationContext<'_>,
404    overloads: &super::resolution::RoutineOverloadContext<'_>,
405    mut plan: UnifiedPlan,
406    params: &[crate::SQLParam],
407    parameters: &crate::binding::RoutineParameterScope,
408) -> Result<(), SQLError> {
409    use crate::plan::CommandPlan;
410    if let UnifiedPlan::Command(command) = plan {
411        match *command {
412            CommandPlan::Explain { body, .. } => {
413                return analyze_sql_standard_utility_input(
414                    context, overloads, *body, params, parameters,
415                )
416            }
417            CommandPlan::CreateTableAs { query, .. }
418            | CommandPlan::CreateMaterializedView { query, .. }
419            | CommandPlan::DeclareCursor { query, .. } => plan = UnifiedPlan::Query(query),
420            command => plan = UnifiedPlan::Command(Box::new(command)),
421        }
422    }
423    let binding = context.catalog.binding_snapshot()?;
424    if matches!(&plan, UnifiedPlan::Command(command) if matches!(command.as_ref(), CommandPlan::Call { .. }))
425    {
426        crate::binding::bind_routine_parameter_references(
427            context.routines,
428            &mut plan,
429            params,
430            &binding.context(),
431            parameters,
432        )?;
433        super::body_validation::analyze_body_statement(
434            &super::body_validation::SQLBodyValidationContext {
435                compilation: *context,
436                overloads: super::resolution::RoutineOverloadContext {
437                    catalog: overloads.catalog,
438                },
439            },
440            &plan,
441            params,
442            &binding,
443            false,
444        )?;
445    } else {
446        crate::binding::analyze_routine_body_inputs(
447            context.routines,
448            &plan,
449            params,
450            &binding.context(),
451            context.catalog,
452            Some(parameters),
453        )?;
454    }
455    Ok(())
456}
457
458/// A successfully analyzed body keeps resolved type identities independently of
459/// its raw source. Domain coercions still resolve current constraint definitions.
460pub fn bind_analyzed_sql_body_types(
461    types: &dyn RoutineTypeCatalog,
462    plan: &mut UnifiedPlan,
463) -> Result<(), SQLError> {
464    crate::binding::stored_types::bind_unified_plan_type_identities(plan, &mut |name| {
465        let resolved = types.resolve_catalog_column_type(name);
466        let mut element = resolved.as_ref();
467        while let Some(ColumnType::Array(inner)) = element {
468            element = Some(inner.as_ref());
469        }
470        let domain = matches!(element, Some(ColumnType::Domain { .. }));
471        Ok(resolved.filter(|_| !domain))
472    })
473}
474
475#[cfg(test)]
476mod tests;