uqa-engine 0.6.3

Engine: schema-aware table store, catalog restore, transactions
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

use crate::Engine;
use uqa_core::Value;
use uqa_execution::routines::{
    context::{
        RoutineExpressions, RoutinePortals, RoutineStatements, RoutineTransactions,
        StatementResultCheck,
    },
    transaction::RoutineSessionId,
    RoutineContext,
};
use uqa_sql::{
    assignment::routines::RoutineValueContext,
    ast::{ColumnType, Expr, FetchCursorStmt, Statement},
    plan::{ExpressionPlan, UnifiedPlan},
    SQLError, SQLParam, SQLResult,
};
impl Engine {
    pub(crate) fn routine_session_id(&self) -> RoutineSessionId {
        RoutineSessionId(std::sync::Arc::as_ptr(&self.session) as usize)
    }
    pub(crate) fn routine_execution_context(&self) -> RoutineContext<'_> {
        RoutineContext {
            expressions: self,
            statements: self,
            transactions: self,
            portals: self,
            session: self.routine_session_id(),
            runtime: self.query_runtime_view(),
            planning: None,
        }
    }
}
impl RoutineValueContext for Engine {
    fn catalog_column_type_with_control(
        &self,
        name: &str,
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<Option<uqa_core::memory::Produced<ColumnType>>, SQLError> {
        uqa_execution::catalog::projection::resolve_catalog_column_type_with_control(
            &self.catalog_execution(),
            name,
            control,
        )
    }

    fn catalog_column_type(&self, name: &str) -> Option<ColumnType> {
        uqa_execution::catalog::projection::resolve_catalog_column_type(
            &self.catalog_execution(),
            name,
        )
    }
}
impl RoutineExpressions for Engine {
    fn expression_type_with_control(
        &self,
        plan: &ExpressionPlan,
        params: &[SQLParam],
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<Option<uqa_core::memory::Produced<ColumnType>>, SQLError> {
        let scope = super::query_scope::new_for_current_routine_with_control(self, control)?;
        let mut binding =
            uqa_execution::query::binding::binding_context_with_control(&scope, control)?;
        binding.scalar_subqueries = &plan.subqueries;
        let resolver = uqa_sql::binding::scoped_types::BindingTypeResolver {
            routines: self,
            scope: &binding,
        };
        let empty = uqa_sql::RowSchema::empty_with_control(control)?;
        uqa_sql::type_resolution::scalar_type_with_resolver_and_control(
            &plan.scalar,
            &empty,
            params,
            Some(&resolver),
            control,
        )
    }
    fn column_type_name(&self, name: &str) -> Result<ColumnType, SQLError> {
        uqa_execution::catalog::projection::resolve_catalog_column_type_name(
            &self.catalog_execution(),
            name,
        )
    }
    fn evaluate(&self, expression: &Expr) -> Result<Value, SQLError> {
        crate::capabilities::query_expressions::eval_lowered_expression(self, expression, None, &[])
    }
    fn evaluate_with_type(
        &self,
        expression: &Expr,
    ) -> Result<uqa_execution::query::catalog_expression::TypedCatalogValue, SQLError> {
        crate::capabilities::query_expressions::eval_lowered_expression_with_type(
            self,
            expression,
            None,
            &[],
        )
    }
    fn expression_type(
        &self,
        plan: &ExpressionPlan,
        params: &[SQLParam],
    ) -> Result<Option<ColumnType>, SQLError> {
        let mut scope = super::query_scope::new_for_current_routine(self)?;
        let resources =
            uqa_execution::query::relational::QueryExpressionFactory::production_resources(self)?;
        scope.scalar_subqueries =
            uqa_sql::plan::RetainedQueryArena::capture(&plan.subqueries, &resources.control())?;
        let hook = uqa_execution::query::relational::context::QueryExpressionFactory::bind_scope(
            self, &scope,
        )?;
        uqa_execution::scalar_type_with_resolver(
            &plan.scalar,
            &uqa_execution::RowSchema::default(),
            params,
            hook.as_ref(),
        )
    }
}
impl RoutineStatements for Engine {
    fn with_statement_scope_with_control(
        &self,
        control: &uqa_core::memory::ProductionControl<'_>,
        analyze: uqa_execution::routines::context::ControlledStatementScopeOperation<'_>,
    ) -> Result<(), SQLError> {
        let scope = super::query_scope::new_for_current_routine_with_control(self, control)?;
        analyze(
            self,
            uqa_execution::query::binding::binding_context_with_control(&scope, control)?,
        )
    }
    fn planning_resources(&self) -> Result<uqa_core::memory::OwnedProductionControl, SQLError> {
        let retained = self.query_retention_control()?;
        Ok(uqa_core::memory::ProductionControl::new(
            retained.memory(),
            retained.cancellation(),
            &self.runtime.cancellation,
        )
        .capture())
    }

    fn body_input_context(
        &self,
    ) -> Option<uqa_execution::routines::sql_body::inputs::SQLRoutineInputContext<'_>> {
        Some(
            uqa_execution::routines::sql_body::inputs::SQLRoutineInputContext {
                cache: self.session.routine_bodies.sql_inputs(),
                analysis: self.prepared_definition_context(),
            },
        )
    }

    fn plpgsql_preparations(
        &self,
        definition: &uqa_sql::ast::CreateFunction,
        parsed: &uqa_sql::plpgsql::PLpgSQLFunction,
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<std::sync::Arc<uqa_execution::routines::preparation::PLpgSQLPreparations>, SQLError>
    {
        self.session
            .routine_bodies
            .plpgsql_preparations(definition, parsed, control)
    }
    fn analyze_static_plan(
        &self,
        plan: &mut UnifiedPlan,
        parameters: &[SQLParam],
    ) -> Result<uqa_sql::binding::statements::ProceduralPlanAnalysis, SQLError> {
        uqa_sql::binding::statements::analyze_procedural_plan(
            &self.statement_planning_context().analysis,
            &uqa_sql::routines::resolution::RoutineOverloadContext { catalog: self },
            self,
            plan,
            parameters,
        )
    }
    fn analyze_static_plan_owned(
        &self,
        plan: uqa_sql::plan::MutableExecutablePlan,
        parameters: &[SQLParam],
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<uqa_sql::binding::statements::OwnedProceduralPlanAnalysis, SQLError> {
        uqa_sql::binding::statements::analyze_procedural_plan_owned(
            &self.statement_planning_context().analysis,
            &uqa_sql::routines::resolution::RoutineOverloadContext { catalog: self },
            self,
            plan,
            parameters,
            control,
        )
    }
    fn parser_settings(&self) -> uqa_sql::parser::ParserSettings {
        Engine::parser_settings(self)
    }
    fn execute_body_statement(
        &self,
        plan: UnifiedPlan,
        params: &[SQLParam],
        check: Option<StatementResultCheck<'_>>,
    ) -> Result<SQLResult, SQLError> {
        let context = self.compiled_statement_context();
        match check {
            Some(check) => uqa_execution::statement::compiled::execute_checked_plan(
                &context, plan, params, check,
            ),
            None => uqa_execution::statement::compiled::execute_plan(&context, plan, params),
        }
    }

    fn select_body_plan(
        &self,
        entry: &uqa_sql::prepared::entry::PreparedStatementPlan,
        params: &[SQLParam],
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<uqa_sql::prepared::planning::PreparedPlanSelection, SQLError> {
        let _statement_thread = self.statement_thread_context().enter();
        uqa_planner::statement_planning::prepared::selection::select_analyzed_entry_with_control(
            &uqa_planner::statement_planning::prepared::selection::PreparedPlanningContext {
                session: self,
                analysis: self.prepared_definition_context(),
                optimization: self,
            },
            entry,
            params,
            control,
        )
    }
    fn select_simple_expression_plan(
        &self,
        entry: &uqa_sql::prepared::entry::PreparedStatementPlan,
        params: &[SQLParam],
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<uqa_sql::prepared::planning::PreparedPlanSelection, SQLError> {
        let _statement_thread = self.statement_thread_context().enter();
        uqa_planner::statement_planning::prepared::selection::select_simple_expression_entry_with_control(
            &uqa_planner::statement_planning::prepared::selection::PreparedPlanningContext {
                session: self,
                analysis: self.prepared_definition_context(),
                optimization: self,
            },
            entry,
            params,
            control,
        )
    }
    fn execute_selected_body_plan(
        &self,
        plan: &UnifiedPlan,
        params: &[SQLParam],
    ) -> Result<SQLResult, SQLError> {
        uqa_execution::statement::compiled::execute_selected_plan(
            &self.compiled_statement_context(),
            plan,
            params,
        )
    }
    fn execute_bound(
        &self,
        statement: Statement,
        params: &[SQLParam],
    ) -> Result<SQLResult, SQLError> {
        uqa_execution::statement::compiled::execute(
            &self.compiled_statement_context(),
            statement,
            params,
        )
    }
    fn execute_text(&self, text: &str, params: &[SQLParam]) -> Result<SQLResult, SQLError> {
        uqa_execution::statement::batch::execute_nested(
            &self.batch_execution_context(),
            text,
            params,
        )
    }
    fn optimize_plan(
        &self,
        plan: UnifiedPlan,
    ) -> Result<uqa_sql::plan::SharedExecutablePlan, SQLError> {
        uqa_planner::statement_planning::executable::optimize_shared_plan(
            &self.statement_planning_context(),
            plan,
        )
    }
    fn optimize_owned_plan(
        &self,
        plan: uqa_sql::plan::MutableExecutablePlan,
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<uqa_sql::plan::SharedExecutablePlan, SQLError> {
        uqa_planner::statement_planning::executable::optimize_owned_with_control(
            &self.statement_planning_context(),
            plan,
            control,
        )?
        .into_shared(control)
    }
    fn assertions_enabled(&self) -> bool {
        self.plpgsql_asserts_enabled()
    }
    fn load_language_library(&self, language: &str) {
        self.load_language(language);
    }
    fn with_statement_scope(
        &self,
        analyze: uqa_execution::routines::context::StatementScopeOperation<'_>,
    ) -> Result<(), SQLError> {
        let scope = super::query_scope::new_for_current_routine(self)?;
        analyze(
            self,
            &uqa_execution::query::binding::binding_context(&scope)?,
        )
    }
}
impl RoutineTransactions for Engine {
    fn depth(&self) -> usize {
        self.transaction_depth()
    }
    fn begin(&self) -> Result<(), SQLError> {
        self.begin()
    }
    fn commit(&self) -> Result<(), SQLError> {
        self.commit()
    }
    fn rollback(&self) -> Result<(), SQLError> {
        self.rollback()
    }
    fn finish_procedural_transaction(&self, commit: bool, chain: bool) -> Result<(), SQLError> {
        self.finish_procedural_transaction(commit, chain)
    }
}
impl RoutinePortals for Engine {
    fn ensure_available(&self, name: &str) -> Result<(), SQLError> {
        uqa_execution::statement::portal::declaration::ensure_plpgsql_session_portal_available(
            self, name,
        )
    }
    fn open(
        &self,
        params: &[SQLParam],
        name: &str,
        scroll: Option<bool>,
        plan: &UnifiedPlan,
        source_sql: &str,
    ) -> Result<(), SQLError> {
        uqa_execution::statement::portal::declaration::open_plpgsql_session_portal(
            &self
                .portal_execution_context()
                .with_source_sql(Some(source_sql)),
            params,
            name,
            scroll,
            plan,
        )
    }
    fn fetch(&self, request: &FetchCursorStmt) -> Result<SQLResult, SQLError> {
        self.fetch_session_portal(request)
    }
    fn close(&self, name: &str) -> Result<(), SQLError> {
        self.close_session_portal(name)
    }
    fn allocate_name(&self) -> String {
        self.allocate_session_portal_name()
    }
    fn pin(&self, name: &str) -> Result<(), SQLError> {
        self.pin_session_portal(name)
    }
    fn unpin(&self, name: &str) -> Result<(), SQLError> {
        self.unpin_session_portal(name)
    }
}