uqa-execution 0.6.3

Volcano physical operators with row-batch pipelines
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Single-query scheduling that seals a bounded result before committing its snapshot.

use super::{
    batch::context::{BatchExecutionContext, CachedStatement},
    plan_executor::UnifiedPlanExecutor,
    transactions::{
        abort_explicit_statement_error, rollback_after_statement_error, rollback_implicit_statement,
    },
};
use crate::query::{cursor::SQLCursor, locking::query_has_row_locks};
use std::sync::Arc;
use uqa_sql::semantics::effects::{query_may_mutate_engine, query_requires_statement_transaction};
use uqa_sql::{plan::UnifiedPlan, SQLError, SQLParam};

pub fn execute<S: Clone + Send + Sync + 'static>(
    context: &BatchExecutionContext<'_, S>,
    sql: &str,
    params: &[SQLParam],
) -> Result<SQLCursor, SQLError> {
    execute_with_context(context, sql, params, false)
}

pub fn execute_nested<S: Clone + Send + Sync + 'static>(
    context: &BatchExecutionContext<'_, S>,
    sql: &str,
    params: &[SQLParam],
) -> Result<SQLCursor, SQLError> {
    execute_with_context(context, sql, params, true)
}

fn execute_with_context<S: Clone + Send + Sync + 'static>(
    context: &BatchExecutionContext<'_, S>,
    sql: &str,
    params: &[SQLParam],
    nested_statement: bool,
) -> Result<SQLCursor, SQLError> {
    let _statement_deadline = (!nested_statement)
        .then(|| crate::statement::batch::context::statement_deadline(context))
        .flatten();
    if let Err(error) = context.runtime.cancellation.check() {
        return Err(abort_explicit_statement_error(
            context.transactions,
            error.into(),
        ));
    }
    context.transactions.refresh_idle_statement_view()?;
    let _statement_thread =
        super::context::statement_thread_scope(context.statements, context.runtime.cancellation);
    let cached = context.cache.cached_sql_statement(sql);
    if !nested_statement
        && !context.persistent_backend
        && context.transactions.transaction_depth() == 0
    {
        if let Some((plan, parser)) = cached.as_ref().and_then(|cached| {
            cached
                .optimized_plan_for(params)
                .map(|plan| (plan, &cached.parser))
        }) {
            if !context.statements.notification_subscriptions_required()
                || matches!(plan.as_ref(), UnifiedPlan::Query(_))
            {
                for notice in parser.notices.iter() {
                    context.runtime.notices.push(notice.clone());
                }
                let executor = UnifiedPlanExecutor::with_nested_statement(
                    context.statements.statement_execution_context(),
                    params,
                    nested_statement,
                );
                return execute_spilled(&executor, plan.as_ref());
            }
        }
    }
    execute_uncached_or_snapshot_scoped(context, sql, params, cached, nested_statement)
}

#[inline(never)]
#[expect(
    clippy::too_many_lines,
    reason = "preserves cursor bounds and position"
)]
fn execute_uncached_or_snapshot_scoped<S: Clone + Send + Sync + 'static>(
    context: &BatchExecutionContext<'_, S>,
    sql: &str,
    params: &[SQLParam],
    cached: Option<CachedStatement>,
    nested_statement: bool,
) -> Result<SQLCursor, SQLError> {
    let planning_owner = context
        .planning
        .planning_control()
        .map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
    let control = planning_owner.control();
    let (statement, initial_plan, cached_optimized, parser) = if let Some(cached) = cached {
        for notice in cached.parser.notices.iter() {
            context.runtime.notices.push(notice.clone());
        }
        let optimized = if nested_statement {
            None
        } else {
            cached.optimized_plan_for(params).cloned()
        };
        let plan = match cached.logical_plan {
            Some(plan) => plan,
            None => super::batch::analysis::lower(&cached.statement, context.aggregates, &control)
                .map_err(|error| abort_explicit_statement_error(context.transactions, error))?,
        };
        (cached.statement, plan, optimized, cached.parser)
    } else {
        let (parsed, parser) =
            uqa_sql::parser::with_settings(context.statements.parser_settings(), || {
                uqa_sql::parse_statements(sql)
            });
        for notice in parser.notices.iter() {
            context.runtime.notices.push(notice.clone());
        }
        let parsed =
            parsed.map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
        if context.statements.notification_subscriptions_required() {
            for statement in &parsed {
                context.runtime.cancellation.check().map_err(|error| {
                    abort_explicit_statement_error(context.transactions, error.into())
                })?;
                if statement.is_notification_listener_command() {
                    return Err(abort_explicit_statement_error(
                        context.transactions,
                        SQLError::NotificationRequiresSubscription,
                    ));
                }
            }
        }
        let mut statements = parsed
            .iter()
            .map(uqa_sql::ParsedStatement::compile)
            .collect::<Result<Vec<_>, _>>()
            .map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
        if statements.len() != 1 {
            return Err(abort_explicit_statement_error(
                context.transactions,
                single_query_error(statements.len()),
            ));
        }
        let statement = Arc::new(statements.remove(0));
        let plan = super::batch::analysis::lower(&statement, context.aggregates, &control)
            .map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
        context
            .cache
            .cache_sql_statement(sql, statement.clone(), None, parser.clone(), &control)
            .map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
        (statement, plan, None, parser)
    };
    if context.statements.notification_subscriptions_required()
        && matches!(
            statement.as_ref(),
            uqa_sql::Statement::Listen { .. } | uqa_sql::Statement::Unlisten { .. }
        )
    {
        return Err(abort_explicit_statement_error(
            context.transactions,
            SQLError::NotificationRequiresSubscription,
        ));
    }
    let query = query_from_plan(initial_plan.as_ref())
        .map_err(|error| abort_explicit_statement_error(context.transactions, error))?;
    let has_row_locks = query_has_row_locks(query);
    let _row_lock_statement = has_row_locks.then(|| context.row_locks.begin_row_lock_statement());

    if context.transactions.transaction_depth() != 0 {
        drop(initial_plan);
        return super::batch::context::with_active_transaction(context.transactions, || {
            if has_row_locks {
                context.row_locks.statement_row_lock_cache()?;
            }
            context
                .transactions
                .prepare_explicit_statement_snapshot(true)?;
            let mut plan = super::batch::analysis::lower(&statement, context.aggregates, &control)?;
            let current_query = query_from_plan(&plan)?;
            context.cache.cache_sql_statement(
                sql,
                statement.clone(),
                Some(plan.clone()),
                parser.clone(),
                &control,
            )?;
            if query_may_mutate_engine(&context.effects.query_effect_context(), current_query)?
                && !has_row_locks
                && context.transactions.prepare_explicit_transaction_writer()?
            {
                drop(plan);
                plan = super::batch::analysis::lower(&statement, context.aggregates, &control)?;
                query_from_plan(&plan)?;
                context.cache.cache_sql_statement(
                    sql,
                    statement.clone(),
                    Some(plan.clone()),
                    parser.clone(),
                    &control,
                )?;
            }
            let optimized = super::batch::analysis::plan(
                context,
                sql,
                plan,
                params,
                !nested_statement,
                false,
                &control,
            )?;
            let executor = UnifiedPlanExecutor::with_nested_statement(
                context.statements.statement_execution_context(),
                params,
                nested_statement,
            );
            execute_spilled(&executor, &optimized)
        });
    }

    let is_read_query = !query_may_mutate_engine(&context.effects.query_effect_context(), query)?;
    let requires_statement_transaction = !is_read_query
        || query_requires_statement_transaction(&context.effects.query_effect_context(), query)?;
    let needs_transaction =
        context.persistent_backend || requires_statement_transaction || has_row_locks;
    if !needs_transaction {
        let optimized = if let Some(plan) = cached_optimized {
            plan
        } else {
            context.cache.retire_sql_logical_plan(sql, &control)?;
            let plan = initial_plan.copy_for_rewrite(&control)?;
            drop(initial_plan);
            let (plan, reusable) = context
                .planning
                .plan_owned_for_statement_cache(plan, params, &control)?;

            if reusable && !nested_statement {
                context
                    .cache
                    .cache_optimized_sql_plan(sql, plan.clone(), &control)?;
            }
            plan
        };
        let executor = UnifiedPlanExecutor::with_nested_statement(
            context.statements.statement_execution_context(),
            params,
            nested_statement,
        );
        return execute_spilled(&executor, optimized.as_ref());
    }

    drop(initial_plan);
    if has_row_locks {
        context.row_locks.statement_row_lock_cache()?;
    }
    context
        .transactions
        .begin_implicit_statement_transaction(is_read_query)?;
    if let Err(error) = context
        .transactions
        .prepare_explicit_statement_snapshot(true)
    {
        return rollback_after_statement_error(context.transactions, error);
    }
    let mut plan = super::batch::analysis::lower(&statement, context.aggregates, &control)
        .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
    context
        .cache
        .cache_sql_statement(
            sql,
            statement.clone(),
            Some(plan.clone()),
            parser.clone(),
            &control,
        )
        .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
    let must_restart_as_writer = if is_read_query && context.persistent_backend && !has_row_locks {
        match query_from_plan(&plan).and_then(|query| {
            query_may_mutate_engine(&context.effects.query_effect_context(), query)
        }) {
            Ok(mutates) => mutates,
            Err(error) => return rollback_after_statement_error(context.transactions, error),
        }
    } else {
        false
    };
    if must_restart_as_writer {
        rollback_implicit_statement(
            context.transactions,
            "restart cursor read transaction as writer",
        )?;
        context
            .transactions
            .begin_implicit_statement_transaction(false)?;
        if let Err(error) = context
            .transactions
            .prepare_explicit_statement_snapshot(true)
        {
            return rollback_after_statement_error(context.transactions, error);
        }
        drop(plan);
        plan = super::batch::analysis::lower(&statement, context.aggregates, &control)
            .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
        if let Err(error) = query_from_plan(&plan) {
            return rollback_after_statement_error(context.transactions, error);
        }
        context
            .cache
            .cache_sql_statement(
                sql,
                statement.clone(),
                Some(plan.clone()),
                parser.clone(),
                &control,
            )
            .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
    }
    let mutating_query = match query_from_plan(&plan)
        .and_then(|query| query_may_mutate_engine(&context.effects.query_effect_context(), query))
    {
        Ok(mutates) => mutates,
        Err(error) => return rollback_after_statement_error(context.transactions, error),
    };
    if mutating_query && context.persistent_backend && !has_row_locks {
        match context.transactions.prepare_explicit_transaction_writer() {
            Ok(true) => {
                drop(plan);
                plan = super::batch::analysis::lower(&statement, context.aggregates, &control)
                    .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
                if let Err(error) = query_from_plan(&plan) {
                    return rollback_after_statement_error(context.transactions, error);
                }
                context
                    .cache
                    .cache_sql_statement(
                        sql,
                        statement.clone(),
                        Some(plan.clone()),
                        parser.clone(),
                        &control,
                    )
                    .or_else(|error| rollback_after_statement_error(context.transactions, error))?;
            }
            Ok(false) => {}
            Err(error) => return rollback_after_statement_error(context.transactions, error),
        }
    }
    let optimized = match super::batch::analysis::plan(
        context,
        sql,
        plan,
        params,
        !nested_statement,
        false,
        &control,
    ) {
        Ok(plan) => plan,
        Err(error) => return rollback_after_statement_error(context.transactions, error),
    };
    let executor = UnifiedPlanExecutor::with_nested_statement(
        context.statements.statement_execution_context(),
        params,
        nested_statement,
    );
    let cursor = match execute_spilled(&executor, &optimized) {
        Ok(cursor) => cursor,
        Err(error) => return rollback_after_statement_error(context.transactions, error),
    };
    context
        .transactions
        .run_transaction_statement(uqa_sql::ast::TransactionStmt::Commit)?;
    Ok(cursor)
}

fn execute_spilled<S: Clone + Send + Sync + 'static>(
    executor: &UnifiedPlanExecutor<'_, '_, S>,
    plan: &UnifiedPlan,
) -> Result<SQLCursor, SQLError> {
    executor.execute_query_to_spill(plan)?.into_cursor()
}

fn query_from_plan(plan: &UnifiedPlan) -> Result<&uqa_sql::plan::QueryPlan, SQLError> {
    let UnifiedPlan::Query(query) = plan else {
        return Err(single_query_error(1));
    };
    Ok(query)
}

fn single_query_error(statement_count: usize) -> SQLError {
    SQLError::Unsupported(format!(
        "SQL cursor accepts exactly one query statement, received {statement_count}"
    ))
}