Skip to main content

uqa_execution/mutation/
command_scope.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Command state boundaries independent of the owning session.
8use crate::query::CteScope;
9use uqa_sql::catalog::roles::RoleReference;
10use uqa_sql::SQLError;
11/// Mutation lifecycle operations on the active transaction frame.
12pub trait MutationCommandState {
13    fn prepare_writer(&self) -> Result<(), SQLError>;
14    fn begin_overlay(&self);
15    fn end_overlay(&self) -> super::overlay::CommandMutationOverlay;
16}
17/// Capture catalog, namespace, trigger transition, and privilege state for a command.
18pub trait CommandScopeSource<S: Clone> {
19    fn command_scope(
20        &self,
21        privilege_subject: Option<&RoleReference>,
22        relations_bound: bool,
23    ) -> Result<CteScope<S>, SQLError>;
24}
25pub struct MutationOverlayScope<'a> {
26    state: Option<&'a dyn MutationCommandState>,
27}
28impl<'a> MutationOverlayScope<'a> {
29    pub fn new(state: &'a dyn MutationCommandState) -> Self {
30        state.begin_overlay();
31        Self { state: Some(state) }
32    }
33
34    pub fn finish(mut self) -> Option<super::overlay::CommandMutationOverlay> {
35        self.state
36            .take()
37            .expect("an active command overlay")
38            .end_overlay()
39            .published_rows()
40    }
41}
42impl Drop for MutationOverlayScope<'_> {
43    fn drop(&mut self) {
44        if let Some(state) = self.state.take() {
45            state.end_overlay();
46        }
47    }
48}
49
50/// Retain the command's original read generation when CTE writes or BEFORE statement triggers can change visible rows.
51pub fn capture_command_read_snapshot<S: Clone + 'static>(
52    snapshots: &dyn crate::query::statement::context::SnapshotSource<S>,
53    inherited: Option<&CteScope<S>>,
54    before_statement_trigger: bool,
55    ctes: &[uqa_sql::plan::CtePlan],
56) -> Result<Option<std::sync::Arc<S>>, SQLError> {
57    match inherited.and_then(CteScope::command_cte_snapshot) {
58        Some(snapshot) => Ok(Some(snapshot)),
59        None if before_statement_trigger || ctes.iter().any(|cte| cte.body.modifies_data()) => {
60            Ok(Some(std::sync::Arc::new(snapshots.capture()?)))
61        }
62        None => Ok(None),
63    }
64}