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