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    /// Tear down engine state cleanly, rolling back open transaction frames
163    /// and clearing registries.
164    /// The engine value can no longer be used afterwards in a
165    /// well-defined sense; idiomatic Rust drops the value at scope
166    /// exit, but this method exists for API compatibility
167    /// reference and for explicit shutdown ordering.
168    pub fn close(&self) -> Result<(), SQLError> {
169        let _statement = self.runtime.statement_gate.lock();
170        // Use the ordinary state machine for every frame. Clearing the stack
171        // before asking SQLite to roll back loses the session snapshot and can
172        // leave dirty flags/caches inconsistent when physical cleanup fails.
173        while self.transaction_depth() != 0 {
174            self.rollback().map_err(|error| {
175                Self::rollback_cleanup_error(
176                    &error,
177                    format!("close: rollback open transaction failed: {error}"),
178                )
179            })?;
180        }
181        // Logical catalog and runtime registries are database state shared by
182        // sibling sessions. Closing one session must not erase them from the
183        // sessions that remain alive.
184        self.release_automatic_statistics_client();
185        self.runtime.terminations.disarm();
186        Ok(())
187    }
188
189    pub(crate) fn ensure_transaction_usable(&self) -> Result<(), SQLError> {
190        if let Some(error) = self
191            .session
192            .transactions
193            .lock()
194            .last()
195            .and_then(|frame| Self::transaction_status_error(frame.status))
196        {
197            return Err(error);
198        }
199        Ok(())
200    }
201
202    pub(crate) fn begin_implicit_statement_transaction(
203        &self,
204        read_only: bool,
205    ) -> Result<(), SQLError> {
206        let _statement = self.lock_statement_gate();
207        let mut stack = self.session.transactions.lock();
208        if !stack.is_empty() {
209            return Err(SQLError::Internal(
210                "implicit statement transaction started inside an explicit transaction".into(),
211            ));
212        }
213        let characteristics = self.default_transaction_characteristics();
214        self.begin_transaction_frame(
215            &mut stack,
216            read_only || characteristics.read_only,
217            true,
218            TransactionFrameKind::ImplicitStatement,
219            characteristics,
220        )
221    }
222
223    /// Start the implicit transaction segment owned by a multi-statement simple-query message.
224    pub fn begin_simple_query_transaction(&self) -> Result<(), SQLError> {
225        let _statement = self.lock_statement_gate();
226        let mut stack = self.session.transactions.lock();
227        if !stack.is_empty() {
228            return Err(SQLError::Internal(
229                "implicit transaction block started inside another transaction".into(),
230            ));
231        }
232        let characteristics = self.default_transaction_characteristics();
233        self.begin_transaction_frame(
234            &mut stack,
235            characteristics.read_only,
236            true,
237            TransactionFrameKind::SimpleQuery,
238            characteristics,
239        )
240    }
241
242    /// Promote the current simple-query transaction to an explicit block after `BEGIN`.
243    pub fn promote_simple_query_transaction(&self) -> Result<(), SQLError> {
244        let mut stack = self.session.transactions.lock();
245        let frame = stack.last_mut().ok_or_else(|| {
246            SQLError::Internal("promote implicit transaction without an open frame".into())
247        })?;
248        frame.implicit_statement = false;
249        frame.explicit_transaction_block = true;
250        Ok(())
251    }
252
253    pub(super) fn begin_transaction_frame(
254        &self,
255        stack: &mut Vec<TransactionFrame>,
256        read_only: bool,
257        defer_write_lock: bool,
258        kind: TransactionFrameKind,
259        mut characteristics: TransactionCharacteristicsState,
260    ) -> Result<(), SQLError> {
261        // 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.
262        if stack
263            .last()
264            .is_some_and(|frame| frame.characteristics.read_only)
265        {
266            characteristics.read_only = true;
267        }
268        let read_only = read_only || characteristics.read_only;
269        let outer = stack.is_empty();
270        let started_at_micros = self.statement_timestamp_micros();
271        let session_snapshot = self.snapshot_session_state();
272        let (storage_savepoint, data_snapshot, snapshot_change_baseline) = if outer {
273            let (data_snapshot, baseline) = self.begin_outer_transaction_with_notifications(
274                read_only,
275                defer_write_lock,
276                &session_snapshot,
277            )?;
278            (None, data_snapshot, baseline)
279        } else {
280            let baseline = stack[0].snapshot_change_baseline.clone();
281            let savepoint = StorageSavepointId::allocate();
282            if let Some(backend) = self.storage.backend.as_ref() {
283                if !Self::backend_savepoints_deferred(stack) {
284                    backend
285                        .savepoint(savepoint)
286                        .map_err(|err| Self::storage_tx_error("nested BEGIN savepoint", &err))?;
287                }
288                (Some(savepoint), None, baseline)
289            } else {
290                (Some(savepoint), self.snapshot_transaction_data()?, baseline)
291            }
292        };
293        let (constraint_modes, deferred_foreign_key_checks, deferred_constraint_trigger_events) =
294            stack.last().map_or_else(
295                || (ConstraintModeState::default(), Vec::new(), Vec::new()),
296                |frame| {
297                    (
298                        frame.constraint_modes.clone(),
299                        frame.deferred_foreign_key_checks.clone(),
300                        frame.deferred_constraint_trigger_events.clone(),
301                    )
302                },
303            );
304        let (lock_mark, next_lock_mark) = stack.last_mut().map_or((0, 1), |frame| {
305            let lock_mark = frame.next_lock_mark;
306            frame.next_lock_mark = frame.next_lock_mark.saturating_add(1);
307            (lock_mark, frame.next_lock_mark)
308        });
309        let backend_mode = self.frame_backend_mode(outer, defer_write_lock);
310        let (implicit_statement, explicit_transaction_block) = match kind {
311            TransactionFrameKind::ExplicitBlock => (false, true),
312            TransactionFrameKind::ImplicitStatement => (true, false),
313            TransactionFrameKind::SimpleQuery => (false, false),
314        };
315        stack.push(TransactionFrame {
316            started_at_micros,
317            implicit_statement,
318            explicit_transaction_block,
319            storage_savepoint,
320            intent: if read_only {
321                TransactionIntent::ReadOnly
322            } else {
323                TransactionIntent::ReadWrite
324            },
325            backend_mode,
326            status: TransactionStatus::Active,
327            characteristics,
328            first_snapshot_set: false,
329            fixed_snapshot: None,
330            fixed_catalog_records: None,
331            fixed_catalog_baseline: None,
332            xid_levels: vec![None],
333            savepoints: Vec::new(),
334            session_snapshot,
335            data_snapshot,
336            dirty_at_begin: self.transaction_dirty_state(),
337            prepared_changes: uqa_execution::statement::prepared::invalidation::PreparedInvalidationLog::default(),
338            begin_lock_mark: lock_mark,
339            lock_mark,
340            next_lock_mark,
341            snapshot_change_baseline: snapshot_change_baseline.clone(),
342            row_changes: Vec::new(),
343            fixed_identities: None,
344            statistics_changes: crate::statistics::StatisticsChanges::new(),
345            statistics_settlement: crate::statistics::StatisticsSettlement::default(),
346            deferred_foreign_key_checks,
347            deferred_constraint_trigger_events,
348            pending_listen_actions: Vec::new(),
349            pending_notifications: Vec::new(),
350            pending_notification_commit: parking_lot::Mutex::new(None),
351            constraint_modes,
352            nontransactional_sequence_values: NontransactionalSequenceValues::new(),
353        });
354        if let Some(savepoint) = storage_savepoint {
355            super::fixed_identities::save_identities(stack, savepoint);
356        }
357        self.update_statement_row_lock_baseline(snapshot_change_baseline);
358        Ok(())
359    }
360
361    /// 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.
362    fn frame_backend_mode(&self, outer: bool, defer_write_lock: bool) -> BackendTransactionMode {
363        if self.versioned_backend_transactions() {
364            BackendTransactionMode::Versioned
365        } else if outer && defer_write_lock && self.storage.backend.is_some() {
366            BackendTransactionMode::Deferred
367        } else {
368            BackendTransactionMode::Writer
369        }
370    }
371
372    fn begin_outer_transaction_with_notifications(
373        &self,
374        read_only: bool,
375        defer_write_lock: bool,
376        session_snapshot: &SessionStateSnapshot,
377    ) -> Result<
378        (
379            Option<EngineDataSnapshot>,
380            crate::row_locks::RowChangeBaseline,
381        ),
382        SQLError,
383    > {
384        self.begin_notification_transaction()?;
385        self.begin_outer_transaction_snapshot(read_only, defer_write_lock, session_snapshot)
386            .map_err(|error| match self.rollback_notification_state() {
387                Ok(()) => error,
388                Err(notification_error) => SQLError::Internal(format!(
389                    "{error}; asynchronous notification begin rollback failed: {notification_error}"
390                )),
391            })
392    }
393
394    /// 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.
395    pub(crate) fn tuple_version_xid(&self) -> Result<u32, SQLError> {
396        let mut stack = self.session.transactions.lock();
397        if stack.is_empty() {
398            drop(stack);
399            return self.row_locks.allocate_transaction_xid();
400        }
401        for frame in stack.iter_mut() {
402            for xid in &mut frame.xid_levels {
403                if xid.is_none() {
404                    *xid = Some(self.row_locks.allocate_transaction_xid()?);
405                }
406            }
407        }
408        stack
409            .last()
410            .and_then(|frame| frame.xid_levels.last())
411            .copied()
412            .flatten()
413            .ok_or_else(|| SQLError::Internal("transaction XID path is empty".into()))
414    }
415
416    fn begin_outer_transaction_snapshot(
417        &self,
418        read_only: bool,
419        defer_write_lock: bool,
420        session_snapshot: &SessionStateSnapshot,
421    ) -> Result<
422        (
423            Option<EngineDataSnapshot>,
424            crate::row_locks::RowChangeBaseline,
425        ),
426        SQLError,
427    > {
428        let Some(backend) = self.storage.backend.as_ref() else {
429            let snapshot_gate = self
430                .row_locks
431                .begin_change_snapshot(&self.runtime.cancellation)?;
432            self.synchronize_table_catalog()
433                .map_err(|err| Self::storage_tx_error("BEGIN table catalog refresh", &err))?;
434            self.synchronize_table_data()
435                .map_err(|err| Self::storage_tx_error("BEGIN table data refresh", &err))?;
436            self.synchronize_catalog_registries()
437                .map_err(|err| Self::storage_tx_error("BEGIN registry refresh", &err))?;
438            return Ok((self.snapshot_transaction_data()?, snapshot_gate.baseline()?));
439        };
440        let snapshot_gate = if backend.transaction_model().is_versioned() {
441            let gate = self
442                .row_locks
443                .begin_change_snapshot(&self.runtime.cancellation)?;
444            backend
445                .begin_upgradeable_transaction()
446                .map_err(|err| Self::storage_tx_error("BEGIN logical transaction", &err))?;
447            gate
448        } else if read_only || defer_write_lock {
449            let gate = self
450                .row_locks
451                .begin_change_snapshot(&self.runtime.cancellation)?;
452            backend
453                .begin_read_transaction()
454                .map_err(|err| Self::storage_tx_error("BEGIN DEFERRED", &err))?;
455            gate
456        } else {
457            // Take the writer registration before the snapshot gate so a writer already committing cannot deadlock with this snapshot.
458            self.acquire_backend_writer_lock(0)?;
459            let gate = match self
460                .row_locks
461                .begin_change_snapshot(&self.runtime.cancellation)
462            {
463                Ok(gate) => gate,
464                Err(error) => {
465                    self.row_locks.release_session(self.session_id);
466                    return Err(error);
467                }
468            };
469            if let Err(err) = backend.begin_transaction() {
470                self.row_locks.release_session(self.session_id);
471                return Err(Self::storage_tx_error("BEGIN", &err));
472            }
473            gate
474        };
475        if let Err(error) = self.refresh_pinned_transaction_snapshot() {
476            let refresh_error = Self::storage_tx_error("BEGIN pinned snapshot refresh", &error);
477            let recovered = self.recover_failed_begin_refresh(
478                backend.as_ref(),
479                session_snapshot,
480                refresh_error,
481            );
482            self.row_locks.release_session(self.session_id);
483            return Err(recovered);
484        }
485        let baseline = match snapshot_gate.baseline() {
486            Ok(baseline) => baseline,
487            Err(error) => {
488                let recovered =
489                    self.recover_failed_begin_refresh(backend.as_ref(), session_snapshot, error);
490                self.row_locks.release_session(self.session_id);
491                return Err(recovered);
492            }
493        };
494        Ok((self.snapshot_transaction_data()?, baseline))
495    }
496
497    /// 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`.
498    pub(super) fn acquire_backend_writer_lock(&self, mark: u32) -> Result<(), SQLError> {
499        self.row_locks.acquire_relation(
500            self.session_id,
501            self.row_locks.backend_writer_key(),
502            crate::row_locks::RelationLockMode::AccessExclusive,
503            mark,
504            &self.runtime.cancellation,
505        )
506    }
507
508    fn recover_failed_begin_refresh(
509        &self,
510        backend: &dyn uqa_storage::PersistentStorageBackend,
511        session_snapshot: &SessionStateSnapshot,
512        refresh_error: SQLError,
513    ) -> SQLError {
514        let mut cleanup_errors = Vec::new();
515        if let Err(error) = backend.rollback_transaction() {
516            cleanup_errors.push(format!("storage rollback: {error}"));
517        } else {
518            self.restore_graph_transaction_overlay(session_snapshot);
519            self.drop_persistent_value_indexes();
520            self.reload_catalogs_after_rollback(&mut cleanup_errors);
521        }
522        self.restore_session_state(session_snapshot);
523        if cleanup_errors.is_empty() {
524            refresh_error
525        } else {
526            SQLError::Internal(format!(
527                "{refresh_error}; failed BEGIN refresh cleanup: {}",
528                cleanup_errors.join("; ")
529            ))
530        }
531    }
532    pub(super) fn storage_tx_error(action: &str, err: &StorageBackendError) -> SQLError {
533        uqa_execution::storage_errors::storage_error(action, err)
534    }
535
536    pub(super) fn transaction_status_error(status: TransactionStatus) -> Option<SQLError> {
537        match status {
538            TransactionStatus::Active => None,
539            TransactionStatus::CommitPending(transaction)
540            | TransactionStatus::RollbackPending(transaction) => {
541                Some(Self::pending_completion_error(
542                    transaction,
543                    "resolve the retained transaction before executing another statement",
544                ))
545            }
546            TransactionStatus::Failed | TransactionStatus::FailedBackendAborted => {
547                Some(failed_transaction_error())
548            }
549        }
550    }
551
552    pub(super) fn pending_completion_error(
553        transaction: uqa_storage::mvcc::TransactionOutcomeId,
554        detail: impl std::fmt::Display,
555    ) -> SQLError {
556        SQLError::Routine {
557            sqlstate: "08007".into(),
558            message: format!(
559                "transaction {transaction:?} requires completion resolution: {detail}"
560            ),
561        }
562    }
563}