Skip to main content

uqa_engine/transactions/
control.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::{
8    failed_transaction_error, Engine, SQLError, TransactionFrame, TransactionFrameKind,
9    TransactionStatus,
10};
11use uqa_sql::ast::TransactionStmt;
12
13impl Engine {
14    pub fn run_transaction_statement(&self, tx: TransactionStmt) -> Result<(), SQLError> {
15        let _statement = self.lock_statement_gate();
16        let apply_on_commit = self.prepare_transaction_completion(&tx)?;
17        let mut guard = self.session.transactions.lock();
18        let failed = guard
19            .last()
20            .is_some_and(|frame| frame.status != TransactionStatus::Active);
21        let outcome = self.dispatch_transaction_statement(&mut guard, tx, failed, apply_on_commit);
22        match outcome {
23            Ok(()) => Ok(()),
24            Err(error) => {
25                // PostgreSQL aborts the enclosing transaction when a savepoint command or nested BEGIN fails; later statements see 25P02 until ROLLBACK. Frames that this failing command could not open or that no longer exist need no abort.
26                let still_open = guard
27                    .last()
28                    .is_some_and(|frame| frame.status == TransactionStatus::Active);
29                drop(guard);
30                if still_open {
31                    return Err(self.abort_sql_transaction_after_error(error));
32                }
33                Err(error)
34            }
35        }
36    }
37
38    pub(crate) fn finish_procedural_transaction(
39        &self,
40        commit: bool,
41        chain: bool,
42    ) -> Result<(), SQLError> {
43        let _statement = self.lock_statement_gate();
44        let chained_characteristics = {
45            let stack = self.session.transactions.lock();
46            let valid = stack.len() == 1
47                && stack.last().is_some_and(|frame| {
48                    frame.implicit_statement
49                        && frame.status == TransactionStatus::Active
50                        && frame.savepoints.is_empty()
51                });
52            if !valid {
53                return Err(invalid_transaction_termination());
54            }
55            stack.last().map(|frame| frame.characteristics)
56        };
57        self.prepare_pinned_session_portals_for_transaction_control()?;
58        self.run_transaction_statement(if commit {
59            TransactionStmt::Commit
60        } else {
61            TransactionStmt::Rollback
62        })?;
63        if self.transaction_depth() != 0 {
64            return Err(SQLError::Internal(
65                "procedural transaction boundary did not close its transaction".into(),
66            ));
67        }
68        let characteristics = if chain {
69            chained_characteristics.ok_or_else(|| {
70                SQLError::Internal(
71                    "procedural transaction chain lost its transaction characteristics".into(),
72                )
73            })?
74        } else {
75            self.default_transaction_characteristics()
76        };
77        let mut stack = self.session.transactions.lock();
78        self.begin_transaction_frame(
79            &mut stack,
80            characteristics.read_only,
81            true,
82            TransactionFrameKind::ImplicitStatement,
83            characteristics,
84        )
85    }
86
87    fn prepare_transaction_completion(&self, tx: &TransactionStmt) -> Result<bool, SQLError> {
88        let apply_on_commit = if matches!(
89            tx,
90            TransactionStmt::Commit | TransactionStmt::CommitAndChain
91        ) {
92            let stack = self.session.transactions.lock();
93            stack.len() == 1
94                && stack
95                    .last()
96                    .is_some_and(|frame| frame.status == TransactionStatus::Active)
97        } else {
98            false
99        };
100        if apply_on_commit {
101            if self.versioned_backend_transactions() {
102                if let Err(error) = self.refresh_explicit_statement_snapshot() {
103                    return Err(self.rollback_transaction_completion_failure(
104                        error,
105                        "commit snapshot refresh",
106                    ));
107                }
108            }
109            // PostgreSQL alternates deferred-trigger processing with WITH HOLD portal conversion until neither phase can enqueue more work. A cursor query may invoke a mutating routine while it is being materialized, so validating only before portal conversion can otherwise commit a newly queued deferred FK violation.
110            loop {
111                self.validate_deferred_constraints_before_outer_commit()?;
112                let materialized = match self.materialize_holdable_session_portals() {
113                    Ok(materialized) => materialized,
114                    Err(error) => {
115                        return Err(self.rollback_transaction_completion_failure(
116                            error,
117                            "holdable cursor materialization",
118                        ));
119                    }
120                };
121                if !materialized {
122                    break;
123                }
124            }
125            if let Err(error) = self.apply_temporary_on_commit_actions() {
126                return Err(self
127                    .rollback_transaction_completion_failure(error, "temporary ON COMMIT action"));
128            }
129        }
130        Ok(apply_on_commit)
131    }
132
133    fn rollback_transaction_completion_failure(&self, error: SQLError, context: &str) -> SQLError {
134        let mut stack = self.session.transactions.lock();
135        match self.rollback_transaction_frame(&mut stack) {
136            Ok(()) => error,
137            Err(rollback_error) => Self::rollback_cleanup_error(
138                &rollback_error,
139                format!("{error}; {context} rollback also failed: {rollback_error}"),
140            ),
141        }
142    }
143
144    fn dispatch_transaction_statement(
145        &self,
146        guard: &mut Vec<TransactionFrame>,
147        tx: TransactionStmt,
148        failed: bool,
149        apply_on_commit: bool,
150    ) -> Result<(), SQLError> {
151        if let Some(
152            status @ (TransactionStatus::CommitPending(transaction)
153            | TransactionStatus::RollbackPending(transaction)),
154        ) = guard.last().map(|frame| frame.status)
155        {
156            let rollback = matches!(status, TransactionStatus::RollbackPending(_));
157            return match tx {
158                TransactionStmt::Commit if rollback => self.rollback_transaction_frame(guard),
159                TransactionStmt::Commit => self.commit_transaction_frame(guard, false),
160                TransactionStmt::CommitAndChain => {
161                    self.finish_transaction_and_chain(guard, "COMMIT", !rollback, false)
162                }
163                TransactionStmt::Rollback => self.rollback_transaction_frame(guard),
164                TransactionStmt::RollbackAndChain => {
165                    self.finish_transaction_and_chain(guard, "ROLLBACK", false, false)
166                }
167                _ => Err(Self::pending_completion_error(
168                    transaction,
169                    "only COMMIT or ROLLBACK can resolve this transaction",
170                )),
171            };
172        }
173        match tx {
174            TransactionStmt::Rollback => self.rollback_transaction_frame(guard),
175            TransactionStmt::Commit if failed => self.rollback_transaction_frame(guard),
176            TransactionStmt::CommitAndChain if failed => {
177                self.finish_transaction_and_chain(guard, "COMMIT", false, false)
178            }
179            TransactionStmt::CommitAndChain => {
180                self.finish_transaction_and_chain(guard, "COMMIT", true, apply_on_commit)
181            }
182            TransactionStmt::RollbackAndChain => {
183                self.finish_transaction_and_chain(guard, "ROLLBACK", false, false)
184            }
185            TransactionStmt::RollbackToSavepoint(name) => {
186                self.rollback_to_transaction_savepoint(guard, &name)
187            }
188            _ if failed => Err(failed_transaction_error()),
189            TransactionStmt::Begin | TransactionStmt::BeginWithCharacteristics(_)
190                if guard.iter().any(|frame| frame.explicit_transaction_block) =>
191            {
192                // PostgreSQL's BeginTransactionBlock warns about a BEGIN inside a transaction block, or inside one of its subtransactions, and changes nothing; the first COMMIT still commits the block.
193                self.push_sql_notice(
194                    uqa_sql::semantics::effects::transaction_blocks::transaction_in_progress_warning(),
195                );
196                Ok(())
197            }
198            TransactionStmt::Begin => {
199                let characteristics = self.transaction_characteristics_for_begin(
200                    guard,
201                    uqa_sql::ast::TransactionCharacteristics::default(),
202                );
203                let outer = guard.is_empty();
204                self.begin_transaction_frame(
205                    guard,
206                    characteristics.read_only,
207                    outer,
208                    TransactionFrameKind::ExplicitBlock,
209                    characteristics,
210                )
211            }
212            TransactionStmt::BeginWithCharacteristics(options) => {
213                let characteristics = self.transaction_characteristics_for_begin(guard, options);
214                let outer = guard.is_empty();
215                self.begin_transaction_frame(
216                    guard,
217                    characteristics.read_only,
218                    outer,
219                    TransactionFrameKind::ExplicitBlock,
220                    characteristics,
221                )
222            }
223            TransactionStmt::Commit => self.commit_transaction_frame(guard, apply_on_commit),
224            TransactionStmt::SetCharacteristics(options) => {
225                Self::apply_transaction_characteristics(guard, options)
226            }
227            TransactionStmt::SetSessionCharacteristics(options) => {
228                self.set_session_transaction_characteristics(options);
229                Ok(())
230            }
231            TransactionStmt::SetSnapshot(snapshot) => {
232                Self::set_transaction_snapshot(guard, &snapshot)
233            }
234            TransactionStmt::Savepoint(name) => self.save_transaction_savepoint(guard, name),
235            TransactionStmt::ReleaseSavepoint(name) => {
236                self.release_transaction_savepoint(guard, &name)
237            }
238        }
239    }
240
241    fn finish_transaction_and_chain(
242        &self,
243        stack: &mut Vec<TransactionFrame>,
244        command: &str,
245        commit: bool,
246        deferred_constraints_validated: bool,
247    ) -> Result<(), SQLError> {
248        let characteristics = stack
249            .last()
250            .ok_or_else(|| SQLError::Routine {
251                sqlstate: "25P01".into(),
252                message: format!("{command} AND CHAIN can only be used in transaction blocks"),
253            })?
254            .characteristics;
255        if commit {
256            self.commit_transaction_frame(stack, deferred_constraints_validated)?;
257        } else {
258            self.rollback_transaction_frame(stack)?;
259        }
260        self.begin_transaction_frame(
261            stack,
262            characteristics.read_only,
263            true,
264            TransactionFrameKind::ExplicitBlock,
265            characteristics,
266        )
267    }
268
269    fn apply_temporary_on_commit_actions(&self) -> Result<(), SQLError> {
270        let actions = self
271            .storage
272            .tables
273            .read()
274            .iter()
275            .filter(|(_, table)| {
276                table.persistence == uqa_sql::ast::RelationPersistence::Temporary
277                    && table.on_commit != uqa_sql::ast::OnCommitAction::PreserveRows
278            })
279            .map(|(relation, table)| (relation.qualified_name(), table.on_commit))
280            .collect::<Vec<_>>();
281        for (name, action) in actions {
282            match action {
283                uqa_sql::ast::OnCommitAction::PreserveRows => {}
284                uqa_sql::ast::OnCommitAction::DeleteRows => {
285                    self.truncate_locked_table(&name, false)?;
286                }
287                uqa_sql::ast::OnCommitAction::Drop => {
288                    self.drop_temporary_table_on_commit_inner(&name)
289                        .map_err(|error| {
290                            SQLError::Internal(format!(
291                                "drop temporary table `{name}` at commit: {error}"
292                            ))
293                        })?;
294                }
295            }
296        }
297        Ok(())
298    }
299}
300
301fn invalid_transaction_termination() -> SQLError {
302    SQLError::Routine {
303        sqlstate: "2D000".into(),
304        message: "invalid transaction termination".into(),
305    }
306}