Skip to main content

uqa_engine/transactions/
coordinator.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Coordination of transaction frames and their storage snapshots.
8//!
9//! Memory snapshot acquisition is ordered by the statement gate, the table registry and its per-table state, the durable registries (`graphs`, `models`, `scoring_params`, `views`, `catalog_indexes`, `database_security`, `schemas`, `path_indexes`, `sequences`, `sequence_object_ids`, `sequence_persistence`, `sequence_security`, `named_analyzers`, `table_field_analyzers`, `foreign_wrappers`, `foreign_servers`, `foreign_tables`, `foreign_table_security`, `sql_user_functions`, `roles`, `role_memberships`, `triggers`, and `rules`), and finally in-memory FDW rows. Durable restore uses the same registry order. Callers must enter through this coordinator instead of holding an individual registry lock across snapshot or restore.
10
11use super::{
12    failed_transaction_error, BackendTransactionMode, ConstraintModeState, Engine,
13    EngineDataSnapshot, NontransactionalSequenceValues, SQLError, SessionStateSnapshot,
14    StorageBackendError, StorageSavepointId, TransactionCharacteristicsState,
15    TransactionDirtyState, TransactionFrame, TransactionFrameKind, TransactionIntent,
16    TransactionStatus,
17};
18
19impl Engine {
20    pub(super) fn transaction_dirty_state(&self) -> TransactionDirtyState {
21        TransactionDirtyState {
22            table_data: self
23                .epochs
24                .table_data
25                .dirty
26                .load(std::sync::atomic::Ordering::Acquire),
27            table_catalog: self
28                .epochs
29                .table_catalog
30                .dirty
31                .load(std::sync::atomic::Ordering::Acquire),
32            catalog_registry: self
33                .epochs
34                .catalog_registry
35                .dirty
36                .load(std::sync::atomic::Ordering::Acquire),
37        }
38    }
39
40    pub(super) fn restore_transaction_dirty_state(&self, state: TransactionDirtyState) {
41        self.epochs
42            .table_data
43            .dirty
44            .store(state.table_data, std::sync::atomic::Ordering::Release);
45        self.epochs
46            .table_catalog
47            .dirty
48            .store(state.table_catalog, std::sync::atomic::Ordering::Release);
49        self.epochs
50            .catalog_registry
51            .dirty
52            .store(state.catalog_registry, std::sync::atomic::Ordering::Release);
53    }
54
55    pub fn begin(&self) -> Result<(), SQLError> {
56        let _statement = self.lock_statement_gate();
57        let mut stack = self.session.transactions.lock();
58        if let Some(error) = stack
59            .last()
60            .and_then(|frame| Self::transaction_status_error(frame.status))
61        {
62            return Err(error);
63        }
64        let characteristics = self.transaction_characteristics_for_begin(
65            &stack,
66            uqa_sql::ast::TransactionCharacteristics::default(),
67        );
68        self.begin_transaction_frame(
69            &mut stack,
70            characteristics.read_only,
71            true,
72            TransactionFrameKind::ExplicitBlock,
73            characteristics,
74        )
75    }
76
77    /// Commit the topmost transaction frame.
78    pub fn commit(&self) -> Result<(), SQLError> {
79        self.run_transaction_statement(uqa_sql::ast::TransactionStmt::Commit)
80    }
81
82    /// Roll back the topmost transaction frame.
83    pub fn rollback(&self) -> Result<(), SQLError> {
84        self.run_transaction_statement(uqa_sql::ast::TransactionStmt::Rollback)
85    }
86
87    /// Mark a savepoint inside the current transaction.
88    pub fn savepoint(&self, name: &str) -> Result<(), SQLError> {
89        self.run_transaction_statement(uqa_sql::ast::TransactionStmt::Savepoint(name.to_string()))
90    }
91
92    /// Release a savepoint.
93    pub fn release_savepoint(&self, name: &str) -> Result<(), SQLError> {
94        self.run_transaction_statement(uqa_sql::ast::TransactionStmt::ReleaseSavepoint(
95            name.to_string(),
96        ))
97    }
98
99    /// Roll back to a named savepoint.
100    pub fn rollback_to_savepoint(&self, name: &str) -> Result<(), SQLError> {
101        self.run_transaction_statement(uqa_sql::ast::TransactionStmt::RollbackToSavepoint(
102            name.to_string(),
103        ))
104    }
105
106    /// Number of currently-open transaction frames (`BEGIN` count
107    /// minus `COMMIT/ROLLBACK` count). Useful for assertions in tests
108    /// and for status displays in the CLI.
109    pub fn transaction_depth(&self) -> usize {
110        self.session_execution_view().transaction_depth()
111    }
112
113    /// Whether the current transaction has failed and requires rollback.
114    /// This reports the engine's transaction state, including failures raised
115    /// outside SQL text execution and recovery through a savepoint.
116    pub fn transaction_failed(&self) -> bool {
117        self.session
118            .transactions
119            .lock()
120            .last()
121            .is_some_and(|frame| {
122                matches!(
123                    frame.status,
124                    TransactionStatus::Failed
125                        | TransactionStatus::FailedBackendAborted
126                        | TransactionStatus::RollbackPending(_)
127                )
128            })
129    }
130
131    /// Physical write identity of an unresolved completion. Read-only serializable completion has no physical receipt; use `pending_transaction_completion` to inspect either kind. Callers must not replay transaction bodies.
132    pub fn pending_commit(&self) -> Option<uqa_storage::mvcc::StorageTransactionId> {
133        match self.pending_transaction_completion()? {
134            uqa_storage::mvcc::TransactionOutcomeId::Records(transaction) => Some(transaction),
135            uqa_storage::mvcc::TransactionOutcomeId::Serializable(_) => None,
136        }
137    }
138
139    /// Retained physical or logical completion identity. Only completion resolution or whole-transaction rollback may proceed while this is present. A failed transaction retains its rollback intent even when the caller requests COMMIT.
140    pub fn pending_transaction_completion(
141        &self,
142    ) -> Option<uqa_storage::mvcc::TransactionOutcomeId> {
143        self.session.transactions.lock().last().and_then(|frame| {
144            if let TransactionStatus::CommitPending(transaction)
145            | TransactionStatus::RollbackPending(transaction) = frame.status
146            {
147                Some(transaction)
148            } else {
149                None
150            }
151        })
152    }
153
154    pub(crate) fn in_transaction_block(&self) -> bool {
155        self.session
156            .transactions
157            .lock()
158            .last()
159            .is_some_and(|frame| !frame.implicit_statement)
160    }
161
162    pub(crate) fn begin_implicit_statement_transaction(
163        &self,
164        read_only: bool,
165    ) -> Result<(), SQLError> {
166        let _statement = self.lock_statement_gate();
167        let mut stack = self.session.transactions.lock();
168        if !stack.is_empty() {
169            return Err(SQLError::Internal(
170                "implicit statement transaction started inside an explicit transaction".into(),
171            ));
172        }
173        let characteristics = self.default_transaction_characteristics();
174        self.begin_transaction_frame(
175            &mut stack,
176            read_only || characteristics.read_only,
177            true,
178            TransactionFrameKind::ImplicitStatement,
179            characteristics,
180        )
181    }
182
183    /// Start the implicit transaction segment owned by a multi-statement simple-query message.
184    pub fn begin_simple_query_transaction(&self) -> Result<(), SQLError> {
185        let _statement = self.lock_statement_gate();
186        let mut stack = self.session.transactions.lock();
187        if !stack.is_empty() {
188            return Err(SQLError::Internal(
189                "implicit transaction block started inside another transaction".into(),
190            ));
191        }
192        let characteristics = self.default_transaction_characteristics();
193        self.begin_transaction_frame(
194            &mut stack,
195            characteristics.read_only,
196            true,
197            TransactionFrameKind::SimpleQuery,
198            characteristics,
199        )
200    }
201
202    /// Promote the current simple-query transaction to an explicit block after `BEGIN`.
203    pub fn promote_simple_query_transaction(&self) -> Result<(), SQLError> {
204        let mut stack = self.session.transactions.lock();
205        let frame = stack.last_mut().ok_or_else(|| {
206            SQLError::Internal("promote implicit transaction without an open frame".into())
207        })?;
208        frame.implicit_statement = false;
209        frame.explicit_transaction_block = true;
210        Ok(())
211    }
212
213    pub(super) fn begin_transaction_frame(
214        &self,
215        stack: &mut Vec<TransactionFrame>,
216        read_only: bool,
217        defer_write_lock: bool,
218        kind: TransactionFrameKind,
219        mut characteristics: TransactionCharacteristicsState,
220    ) -> Result<(), SQLError> {
221        // A PostgreSQL subtransaction cannot relax the enclosing transaction's read-only mode. This is also the invariant relied on by PL/pgSQL EXCEPTION blocks, which use nested engine frames as subtransactions.
222        if stack
223            .last()
224            .is_some_and(|frame| frame.characteristics.read_only)
225        {
226            characteristics.read_only = true;
227        }
228        let read_only = read_only || characteristics.read_only;
229        let outer = stack.is_empty();
230        let started_at_micros = self.statement_timestamp_micros();
231        let session_snapshot = self.snapshot_session_state();
232        let (storage_savepoint, data_snapshot, snapshot_change_baseline) = if outer {
233            let (data_snapshot, baseline) = self.begin_outer_transaction_with_notifications(
234                read_only,
235                defer_write_lock,
236                &session_snapshot,
237            )?;
238            (None, data_snapshot, baseline)
239        } else {
240            let baseline = stack[0].snapshot_change_baseline.clone();
241            let savepoint = StorageSavepointId::allocate();
242            if let Some(backend) = self.storage.backend.as_ref() {
243                if !Self::backend_savepoints_deferred(stack) {
244                    backend
245                        .savepoint(savepoint)
246                        .map_err(|err| Self::storage_tx_error("nested BEGIN savepoint", &err))?;
247                }
248                (Some(savepoint), None, baseline)
249            } else {
250                (Some(savepoint), self.snapshot_transaction_data()?, baseline)
251            }
252        };
253        let (constraint_modes, deferred_foreign_key_checks, deferred_constraint_trigger_events) =
254            stack.last().map_or_else(
255                || (ConstraintModeState::default(), Vec::new(), Vec::new()),
256                |frame| {
257                    (
258                        frame.constraint_modes.clone(),
259                        frame.deferred_foreign_key_checks.clone(),
260                        frame.deferred_constraint_trigger_events.clone(),
261                    )
262                },
263            );
264        let (lock_mark, next_lock_mark) = stack.last_mut().map_or((0, 1), |frame| {
265            let lock_mark = frame.next_lock_mark;
266            frame.next_lock_mark = frame.next_lock_mark.saturating_add(1);
267            (lock_mark, frame.next_lock_mark)
268        });
269        let backend_mode = self.frame_backend_mode(outer, defer_write_lock);
270        let (implicit_statement, explicit_transaction_block) = match kind {
271            TransactionFrameKind::ExplicitBlock => (false, true),
272            TransactionFrameKind::ImplicitStatement => (true, false),
273            TransactionFrameKind::SimpleQuery => (false, false),
274        };
275        stack.push(TransactionFrame {
276            started_at_micros,
277            implicit_statement,
278            explicit_transaction_block,
279            storage_savepoint,
280            intent: if read_only {
281                TransactionIntent::ReadOnly
282            } else {
283                TransactionIntent::ReadWrite
284            },
285            backend_mode,
286            status: TransactionStatus::Active,
287            characteristics,
288            first_snapshot_set: false,
289            fixed_snapshot: None,
290            fixed_catalog_records: None,
291            fixed_catalog_baseline: None,
292            xid_levels: vec![None],
293            savepoints: Vec::new(),
294            session_snapshot,
295            data_snapshot,
296            dirty_at_begin: self.transaction_dirty_state(),
297            prepared_changes: uqa_execution::statement::prepared::invalidation::PreparedInvalidationLog::default(),
298            begin_lock_mark: lock_mark,
299            lock_mark,
300            next_lock_mark,
301            snapshot_change_baseline: snapshot_change_baseline.clone(),
302            row_changes: Vec::new(),
303            fixed_identities: None,
304            statistics_changes: crate::statistics::StatisticsChanges::new(),
305            statistics_settlement: crate::statistics::StatisticsSettlement::default(),
306            deferred_foreign_key_checks,
307            deferred_constraint_trigger_events,
308            pending_listen_actions: Vec::new(),
309            pending_notifications: Vec::new(),
310            pending_notification_commit: parking_lot::Mutex::new(None),
311            constraint_modes,
312            nontransactional_sequence_values: NontransactionalSequenceValues::new(),
313        });
314        if let Some(savepoint) = storage_savepoint {
315            super::fixed_identities::save_identities(stack, savepoint);
316        }
317        self.update_statement_row_lock_baseline(snapshot_change_baseline);
318        Ok(())
319    }
320
321    /// The backend transaction mode of a new frame: every frame of a versioned backend is versioned, and an outer frame that defers its write lock on a backend begins without it.
322    fn frame_backend_mode(&self, outer: bool, defer_write_lock: bool) -> BackendTransactionMode {
323        if self.versioned_backend_transactions() {
324            BackendTransactionMode::Versioned
325        } else if outer && defer_write_lock && self.storage.backend.is_some() {
326            BackendTransactionMode::Deferred
327        } else {
328            BackendTransactionMode::Writer
329        }
330    }
331
332    fn begin_outer_transaction_with_notifications(
333        &self,
334        read_only: bool,
335        defer_write_lock: bool,
336        session_snapshot: &SessionStateSnapshot,
337    ) -> Result<
338        (
339            Option<EngineDataSnapshot>,
340            crate::row_locks::RowChangeBaseline,
341        ),
342        SQLError,
343    > {
344        self.begin_notification_transaction()?;
345        self.begin_outer_transaction_snapshot(read_only, defer_write_lock, session_snapshot)
346            .map_err(|error| match self.rollback_notification_state() {
347                Ok(()) => error,
348                Err(notification_error) => SQLError::Internal(format!(
349                    "{error}; asynchronous notification begin rollback failed: {notification_error}"
350                )),
351            })
352    }
353
354    /// Return the transaction ID that creates a new tuple version. IDs are allocated lazily, and a first write below a savepoint allocates every missing ancestor ID before the active subtransaction ID, matching `PostgreSQL`'s top-XID/sub-XID hierarchy. Direct in-memory APIs intentionally omit a heavyweight transaction snapshot when no frame is open; each such autocommit row write still receives its own durable XID.
355    pub(crate) fn tuple_version_xid(&self) -> Result<u32, SQLError> {
356        let mut stack = self.session.transactions.lock();
357        if stack.is_empty() {
358            drop(stack);
359            return self.row_locks.allocate_transaction_xid();
360        }
361        for frame in stack.iter_mut() {
362            for xid in &mut frame.xid_levels {
363                if xid.is_none() {
364                    *xid = Some(self.row_locks.allocate_transaction_xid()?);
365                }
366            }
367        }
368        stack
369            .last()
370            .and_then(|frame| frame.xid_levels.last())
371            .copied()
372            .flatten()
373            .ok_or_else(|| SQLError::Internal("transaction XID path is empty".into()))
374    }
375
376    fn begin_outer_transaction_snapshot(
377        &self,
378        read_only: bool,
379        defer_write_lock: bool,
380        session_snapshot: &SessionStateSnapshot,
381    ) -> Result<
382        (
383            Option<EngineDataSnapshot>,
384            crate::row_locks::RowChangeBaseline,
385        ),
386        SQLError,
387    > {
388        let Some(backend) = self.storage.backend.as_ref() else {
389            let snapshot_gate = self
390                .row_locks
391                .begin_change_snapshot(&self.runtime.cancellation)?;
392            self.synchronize_table_catalog()
393                .map_err(|err| Self::storage_tx_error("BEGIN table catalog refresh", &err))?;
394            self.synchronize_table_data()
395                .map_err(|err| Self::storage_tx_error("BEGIN table data refresh", &err))?;
396            self.synchronize_catalog_registries()
397                .map_err(|err| Self::storage_tx_error("BEGIN registry refresh", &err))?;
398            return Ok((self.snapshot_transaction_data()?, snapshot_gate.baseline()?));
399        };
400        let snapshot_gate = if backend.transaction_model().is_versioned() {
401            let gate = self
402                .row_locks
403                .begin_change_snapshot(&self.runtime.cancellation)?;
404            backend
405                .begin_upgradeable_transaction()
406                .map_err(|err| Self::storage_tx_error("BEGIN logical transaction", &err))?;
407            gate
408        } else if read_only || defer_write_lock {
409            let gate = self
410                .row_locks
411                .begin_change_snapshot(&self.runtime.cancellation)?;
412            backend
413                .begin_read_transaction()
414                .map_err(|err| Self::storage_tx_error("BEGIN DEFERRED", &err))?;
415            gate
416        } else {
417            // Take the writer registration before the snapshot gate so a writer already committing cannot deadlock with this snapshot.
418            self.acquire_backend_writer_lock(0)?;
419            let gate = match self
420                .row_locks
421                .begin_change_snapshot(&self.runtime.cancellation)
422            {
423                Ok(gate) => gate,
424                Err(error) => {
425                    self.row_locks.release_session(self.session_id);
426                    return Err(error);
427                }
428            };
429            if let Err(err) = backend.begin_transaction() {
430                self.row_locks.release_session(self.session_id);
431                return Err(Self::storage_tx_error("BEGIN", &err));
432            }
433            gate
434        };
435        if let Err(error) = self.refresh_pinned_transaction_snapshot() {
436            let refresh_error = Self::storage_tx_error("BEGIN pinned snapshot refresh", &error);
437            let recovered = self.recover_failed_begin_refresh(
438                backend.as_ref(),
439                session_snapshot,
440                refresh_error,
441            );
442            self.row_locks.release_session(self.session_id);
443            return Err(recovered);
444        }
445        let baseline = match snapshot_gate.baseline() {
446            Ok(baseline) => baseline,
447            Err(error) => {
448                let recovered =
449                    self.recover_failed_begin_refresh(backend.as_ref(), session_snapshot, error);
450                self.row_locks.release_session(self.session_id);
451                return Err(recovered);
452            }
453        };
454        Ok((self.snapshot_transaction_data()?, baseline))
455    }
456
457    /// Register the physical backend writer this session holds in the logical lock manager. Eager writer frames (typed `begin`, direct transactions) and promoted deferred frames must both hold the structural backend-writer lock, otherwise a writer blocked on a row lock is invisible to the deadlock detector and a promoting SQL session waits at the storage layer instead of reporting `40P01`.
458    pub(super) fn acquire_backend_writer_lock(&self, mark: u32) -> Result<(), SQLError> {
459        self.row_locks.acquire_relation(
460            self.session_id,
461            self.row_locks.backend_writer_key(),
462            crate::row_locks::RelationLockMode::AccessExclusive,
463            mark,
464            &self.runtime.cancellation,
465        )
466    }
467
468    fn recover_failed_begin_refresh(
469        &self,
470        backend: &dyn uqa_storage::PersistentStorageBackend,
471        session_snapshot: &SessionStateSnapshot,
472        refresh_error: SQLError,
473    ) -> SQLError {
474        let mut cleanup_errors = Vec::new();
475        if let Err(error) = backend.rollback_transaction() {
476            cleanup_errors.push(format!("storage rollback: {error}"));
477        } else {
478            self.restore_graph_transaction_overlay(session_snapshot);
479            self.drop_persistent_value_indexes();
480            self.reload_catalogs_after_rollback(&mut cleanup_errors);
481        }
482        self.restore_session_state(session_snapshot);
483        if cleanup_errors.is_empty() {
484            refresh_error
485        } else {
486            SQLError::Internal(format!(
487                "{refresh_error}; failed BEGIN refresh cleanup: {}",
488                cleanup_errors.join("; ")
489            ))
490        }
491    }
492    pub(super) fn storage_tx_error(action: &str, err: &StorageBackendError) -> SQLError {
493        uqa_execution::storage_errors::storage_error(action, err)
494    }
495
496    pub(super) fn transaction_status_error(status: TransactionStatus) -> Option<SQLError> {
497        match status {
498            TransactionStatus::Active => None,
499            TransactionStatus::CommitPending(transaction)
500            | TransactionStatus::RollbackPending(transaction) => {
501                Some(Self::pending_completion_error(
502                    transaction,
503                    "resolve the retained transaction before executing another statement",
504                ))
505            }
506            TransactionStatus::Failed | TransactionStatus::FailedBackendAborted => {
507                Some(failed_transaction_error())
508            }
509        }
510    }
511
512    pub(super) fn pending_completion_error(
513        transaction: uqa_storage::mvcc::TransactionOutcomeId,
514        detail: impl std::fmt::Display,
515    ) -> SQLError {
516        SQLError::Routine {
517            sqlstate: "08007".into(),
518            message: format!(
519                "transaction {transaction:?} requires completion resolution: {detail}"
520            ),
521        }
522    }
523}