Skip to main content

uqa_engine/transactions/
implicit.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Scoped transaction callbacks and implicit transaction lifecycle.
8
9use super::{
10    panic_description, BackendTransactionMode, Engine, SQLError, SQLParam, SQLResult,
11    StorageBackendError, StorageBackendResult, TransactionScope,
12};
13use uqa_sql::SQLBatchError;
14
15#[cfg(test)]
16#[path = "batch_diagnostic_tests.rs"]
17mod batch_diagnostic_tests;
18
19#[derive(Clone, Copy)]
20enum DefinitionAdmission {
21    Direct,
22    Statement,
23}
24
25impl Engine {
26    /// Run `f` inside one engine transaction. An error or panic from `f` rolls back the transaction. A successful callback commits; an indeterminate commit retains its sealed attempt in the session for resolution through `commit` or `rollback`, without replaying `f`.
27    pub fn transaction<R>(
28        &self,
29        f: impl FnOnce(&Self) -> Result<R, SQLError>,
30    ) -> Result<R, SQLError> {
31        self.transaction_with_error(f, std::convert::identity)
32    }
33
34    pub(crate) fn transaction_with_error<R, E: super::TransactionError>(
35        &self,
36        f: impl FnOnce(&Self) -> Result<R, E>,
37        map_transaction_error: impl Fn(SQLError) -> E,
38    ) -> Result<R, E> {
39        let _statement = self.lock_statement_gate();
40        let scope = TransactionScope::begin(self).map_err(&map_transaction_error)?;
41        self.run_transaction_scope(scope, f, map_transaction_error)
42    }
43
44    pub(super) fn run_transaction_scope<R, E: super::TransactionError>(
45        &self,
46        mut scope: TransactionScope<'_>,
47        f: impl FnOnce(&Self) -> Result<R, E>,
48        map_transaction_error: impl Fn(SQLError) -> E,
49    ) -> Result<R, E> {
50        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
51        match result {
52            Ok(Ok(value)) => {
53                scope.commit().map_err(&map_transaction_error)?;
54                Ok(value)
55            }
56            Ok(Err(err)) => {
57                if let Err(rollback_err) = scope.rollback() {
58                    return Err(super::error::attach(
59                        err,
60                        rollback_err,
61                        "transaction rollback after error failed",
62                        map_transaction_error,
63                    ));
64                }
65                Err(err)
66            }
67            Err(payload) => match scope.rollback() {
68                Ok(()) => std::panic::resume_unwind(payload),
69                Err(rollback_err) => Err(map_transaction_error(Self::rollback_cleanup_error(
70                    &rollback_err,
71                    format!(
72                    "transaction rollback after panic failed: {rollback_err}; original panic: {}",
73                    panic_description(payload.as_ref())
74                ),
75                ))),
76            },
77        }
78    }
79
80    /// Admit a public query through the active transaction or an owned implicit frame. Queries that can persist calibration or create a graph need a writable snapshot, including on memory engines. Attached physical readers retain their existing view and completion owner.
81    pub(crate) fn with_query_transaction_snapshot<R, E: super::TransactionError>(
82        &self,
83        select_snapshot: bool,
84        read_only: bool,
85        query: impl FnOnce(&Self) -> Result<R, E>,
86        map_transaction_error: impl Fn(SQLError) -> E,
87    ) -> Result<R, E> {
88        if read_only && self.query_table_snapshots.is_some() {
89            // Captured readers borrow the source session but already own their data and catalog view. Admitting another statement on that shared session would refresh its live transaction underneath the retained read.
90            self.runtime
91                .cancellation
92                .check()
93                .map_err(SQLError::from)
94                .map_err(&map_transaction_error)?;
95            return query(self);
96        }
97        if self.transaction_depth() != 0 {
98            return self.run_existing_transaction_operation(
99                || {
100                    self.runtime
101                        .cancellation
102                        .check()
103                        .map_err(SQLError::from)
104                        .map_err(&map_transaction_error)?;
105                    if select_snapshot {
106                        self.prepare_explicit_statement_snapshot(true)
107                            .map_err(&map_transaction_error)?;
108                        self.mark_transaction_snapshot_set();
109                    }
110                    query(self)
111                },
112                &map_transaction_error,
113            );
114        }
115        self.runtime
116            .cancellation
117            .check()
118            .map_err(SQLError::from)
119            .map_err(&map_transaction_error)?;
120        if self
121            .storage
122            .backend
123            .as_ref()
124            .map_or(read_only, |backend| backend.in_transaction())
125        {
126            return query(self);
127        }
128        let scope = TransactionScope::begin_implicit_statement(self, read_only)
129            .map_err(&map_transaction_error)?;
130        self.run_transaction_scope(
131            scope,
132            |engine| {
133                engine
134                    .prepare_explicit_statement_snapshot(true)
135                    .map_err(&map_transaction_error)?;
136                engine.mark_transaction_snapshot_set();
137                query(engine)
138            },
139            &map_transaction_error,
140        )
141    }
142
143    /// Make a direct persistent-engine mutation atomic. A failed mutation in an existing transaction aborts its current frame or user savepoint through the same recovery boundary as SQL. Memory stores validate fallible vector input before their infallible writes; explicit memory transactions retain writable snapshots whose document and inverted-index state is copied on mutation. Avoiding a whole-engine snapshot for each direct memory insert keeps bulk ingestion linear.
144    pub(crate) fn with_implicit_transaction<R>(
145        &self,
146        f: impl FnOnce(&Self) -> Result<R, SQLError>,
147    ) -> Result<R, SQLError> {
148        self.with_implicit_mapped_transaction(f, std::convert::identity)
149    }
150
151    pub(super) fn with_implicit_transaction_mutation<R>(
152        &self,
153        f: impl FnOnce(&Self) -> Result<R, SQLError>,
154    ) -> Result<R, SQLError> {
155        let _statement = self.lock_statement_gate();
156        if self.transaction_depth() != 0 {
157            return self.run_existing_transaction_operation(|| f(self), std::convert::identity);
158        }
159        if self.storage.backend.is_none() {
160            return f(self);
161        }
162        self.transaction(f)
163    }
164
165    /// Definition changes need transaction-owned relation locks even for direct memory APIs. Defer physical writer admission until execution has acquired and revalidated those locks.
166    pub(crate) fn with_implicit_definition_transaction<R>(
167        &self,
168        f: impl FnOnce(&Self) -> Result<R, SQLError>,
169    ) -> Result<R, SQLError> {
170        self.with_definition_transaction(DefinitionAdmission::Direct, f)
171    }
172
173    /// Run an admitted SQL definition's publication under the transaction owner. Direct definition APIs apply their own admission policy through the same boundary.
174    pub(crate) fn with_definition_publication<R>(
175        &self,
176        f: impl FnOnce(&Self) -> Result<R, SQLError>,
177    ) -> Result<R, SQLError> {
178        self.with_definition_transaction(DefinitionAdmission::Statement, f)
179    }
180
181    fn with_definition_transaction<R>(
182        &self,
183        admission: DefinitionAdmission,
184        f: impl FnOnce(&Self) -> Result<R, SQLError>,
185    ) -> Result<R, SQLError> {
186        let _statement = self.lock_statement_gate();
187        let operation = |engine: &Self| {
188            if matches!(admission, DefinitionAdmission::Direct)
189                && engine.current_transaction_is_read_only()
190            {
191                return Err(SQLError::Routine {
192                    sqlstate: "25006".into(),
193                    message: "cannot execute direct mutation in a read-only transaction".into(),
194                });
195            }
196            engine.prepare_serializable_transaction_snapshot()?;
197            let value = f(engine)?;
198            engine.publish_catalog_constraint_tuples()?;
199            Ok(value)
200        };
201        if self.transaction_depth() != 0 {
202            self.run_existing_transaction_operation(|| operation(self), std::convert::identity)
203        } else {
204            self.transaction(operation)
205        }
206    }
207
208    /// Error-type-preserving counterpart for direct APIs whose public error
209    /// type is not [`SQLError`]. `map_transaction_error` is used only for
210    /// begin/commit/rollback infrastructure failures; an error returned by
211    /// `f` is passed through unchanged when rollback succeeds.
212    pub(crate) fn with_implicit_mapped_transaction<R, E>(
213        &self,
214        f: impl FnOnce(&Self) -> Result<R, E>,
215        map_transaction_error: impl Fn(SQLError) -> E,
216    ) -> Result<R, E>
217    where
218        E: super::TransactionError,
219    {
220        let _statement = self.lock_statement_gate();
221        let existing_transaction = self.transaction_depth() != 0;
222        let prepare_writer = existing_transaction || self.storage.backend.is_some();
223        let operation = |engine: &Self| {
224            if engine.current_transaction_is_read_only() {
225                return Err(map_transaction_error(SQLError::Routine {
226                    sqlstate: "25006".into(),
227                    message: "cannot execute direct mutation in a read-only transaction".into(),
228                }));
229            }
230            if prepare_writer {
231                engine
232                    .prepare_explicit_transaction_writer()
233                    .map_err(&map_transaction_error)?;
234            }
235            f(engine)
236        };
237        if existing_transaction {
238            return self
239                .run_existing_transaction_operation(|| operation(self), &map_transaction_error);
240        }
241        if self.storage.backend.is_none() {
242            return operation(self);
243        }
244        let scope = TransactionScope::begin(self).map_err(&map_transaction_error)?;
245        self.run_transaction_scope(scope, operation, &map_transaction_error)
246    }
247
248    /// Storage-facing counterpart of [`Engine::with_implicit_transaction`].
249    /// The storage error is retained verbatim when rollback succeeds so API
250    /// callers can still classify the original backend failure.
251    pub(crate) fn with_implicit_storage_transaction<R>(
252        &self,
253        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
254    ) -> StorageBackendResult<R> {
255        self.with_implicit_storage_transaction_inner(false, true, f)
256    }
257
258    /// Complete direct schema publication within the same storage transaction and preserve its public error type.
259    pub(crate) fn with_implicit_storage_definition_transaction<R>(
260        &self,
261        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
262    ) -> StorageBackendResult<R> {
263        self.with_implicit_storage_transaction(|engine| {
264            let result = f(engine)?;
265            engine
266                .publish_catalog_constraint_tuples()
267                .map_err(|error| StorageBackendError::backend("constraint publication", error))?;
268            Ok(result)
269        })
270    }
271
272    /// Run storage maintenance that `PostgreSQL` permits in a read-only transaction. The transaction remains logically read-only, while its physical backend is allowed to persist maintenance metadata such as ANALYZE statistics.
273    pub(crate) fn with_read_only_compatible_storage_transaction<R>(
274        &self,
275        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
276    ) -> StorageBackendResult<R> {
277        self.with_storage_maintenance_scope(|engine| {
278            engine.prepare_storage_maintenance_writer()?;
279            f(engine)
280        })
281    }
282
283    /// Establish the maintenance transaction before execution acquires logical locks or samples rows. Physical write admission is deferred until the caller has finished every required logical wait.
284    pub(crate) fn with_storage_maintenance_scope<R>(
285        &self,
286        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
287    ) -> StorageBackendResult<R> {
288        self.with_implicit_storage_transaction_inner(true, false, f)
289    }
290
291    pub(crate) fn prepare_storage_maintenance_writer(&self) -> StorageBackendResult<()> {
292        self.prepare_explicit_transaction_writer()
293            .map_err(|error| StorageBackendError::backend("maintenance transaction", error))?;
294        Ok(())
295    }
296
297    /// Automatic maintenance must release its relation locks instead of waiting behind a serialized writer that may need to upgrade those same locks.
298    pub(crate) fn try_prepare_storage_maintenance_writer(&self) -> StorageBackendResult<bool> {
299        let mark = self
300            .session
301            .transactions
302            .lock()
303            .first()
304            .filter(|frame| frame.backend_mode == BackendTransactionMode::Deferred)
305            .map(|frame| frame.begin_lock_mark);
306        if let Some(mark) = mark {
307            let admitted = self
308                .row_locks
309                .try_acquire_relation(
310                    self.session_id,
311                    self.row_locks.backend_writer_key(),
312                    crate::row_locks::RelationLockMode::AccessExclusive,
313                    mark,
314                    &self.runtime.cancellation,
315                )
316                .map_err(|error| {
317                    StorageBackendError::backend("maintenance writer admission", error)
318                })?;
319            if !admitted {
320                return Ok(false);
321            }
322        }
323        self.prepare_storage_maintenance_writer()?;
324        Ok(true)
325    }
326
327    fn with_implicit_storage_transaction_inner<R>(
328        &self,
329        maintenance: bool,
330        promote_writer: bool,
331        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
332    ) -> StorageBackendResult<R> {
333        let _statement = self.lock_statement_gate();
334        let operation = |engine: &Self| {
335            if !maintenance && engine.current_transaction_is_read_only() {
336                return Err(StorageBackendError::backend(
337                    "storage mutation",
338                    SQLError::Routine {
339                        sqlstate: "25006".into(),
340                        message: "cannot execute storage mutation in a read-only transaction"
341                            .into(),
342                    },
343                ));
344            }
345            engine
346                .prepare_serializable_transaction_snapshot()
347                .map_err(|error| StorageBackendError::backend("maintenance snapshot", error))?;
348            if promote_writer {
349                engine
350                    .prepare_explicit_transaction_writer()
351                    .map_err(|error| {
352                        StorageBackendError::backend("promote storage transaction", error)
353                    })?;
354            }
355            f(engine)
356        };
357        if self.transaction_depth() != 0 {
358            return self.run_existing_transaction_operation(
359                || operation(self),
360                |error| StorageBackendError::backend("transaction abort", error),
361            );
362        }
363        let scope = TransactionScope::begin(self).map_err(|error| {
364            StorageBackendError::backend("begin implicit storage transaction", error)
365        })?;
366        self.run_transaction_scope(scope, operation, |error| {
367            StorageBackendError::backend("storage transaction", error)
368        })
369    }
370
371    pub(crate) fn with_implicit_string_transaction<R>(
372        &self,
373        f: impl FnOnce(&Self) -> Result<R, String>,
374    ) -> Result<R, String> {
375        let _statement = self.lock_statement_gate();
376        if self.transaction_depth() != 0 {
377            return self.run_existing_transaction_operation(
378                || {
379                    self.prepare_explicit_transaction_writer()
380                        .map_err(|error| {
381                            format!("promote explicit engine transaction failed: {error}")
382                        })?;
383                    f(self)
384                },
385                |error| error.to_string(),
386            );
387        }
388        let mut scope = TransactionScope::begin(self)
389            .map_err(|error| format!("begin implicit engine transaction failed: {error}"))?;
390        if let Err(error) = self.prepare_explicit_transaction_writer() {
391            let error = format!("promote implicit engine transaction failed: {error}");
392            return match scope.rollback() {
393                Ok(()) => Err(error),
394                Err(rollback_error) => Err(format!(
395                    "rollback implicit engine transaction after promotion failure failed: {rollback_error}; original error: {error}"
396                )),
397            };
398        }
399        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
400        match result {
401            Ok(Ok(value)) => {
402                scope
403                    .commit()
404                    .map_err(|error| format!("commit implicit engine transaction failed: {error}"))?;
405                Ok(value)
406            }
407            Ok(Err(error)) => match scope.rollback() {
408                Ok(()) => Err(error),
409                Err(rollback_error) => Err(format!(
410                    "rollback implicit engine transaction failed: {rollback_error}; original error: {error}"
411                )),
412            },
413            Err(payload) => match scope.rollback() {
414                Ok(()) => std::panic::resume_unwind(payload),
415                Err(rollback_error) => Err(format!(
416                    "rollback implicit engine transaction after panic failed: {rollback_error}; original panic: {}",
417                    panic_description(payload.as_ref())
418                )),
419            },
420        }
421    }
422
423    /// Execute multiple SQL statements inside one engine transaction.
424    pub fn sql_batch(
425        &self,
426        statements: &[(&str, &[SQLParam])],
427    ) -> Result<Vec<SQLResult>, SQLError> {
428        self.sql_batch_diagnosed(statements)
429            .map_err(SQLBatchError::into_error)
430    }
431
432    /// Execute the same atomic batch while retaining the zero-based failing member.
433    /// Transaction-boundary failures carry no member; no statement is retried.
434    pub fn sql_batch_diagnosed(
435        &self,
436        statements: &[(&str, &[SQLParam])],
437    ) -> Result<Vec<SQLResult>, SQLBatchError> {
438        self.sql_batch_observed(statements, |_, _| Ok(()))
439    }
440
441    /// Execute multiple SQL statements inside one engine transaction like [`Engine::sql_batch`], replacing each result's enum values by their labels before the next statement runs, so a later statement cannot remove a type an earlier result still names. Host bindings return these results.
442    pub fn sql_batch_with_labels(
443        &self,
444        statements: &[(&str, &[SQLParam])],
445    ) -> Result<Vec<SQLResult>, SQLError> {
446        self.sql_batch_observed(statements, Engine::render_enum_labels)
447            .map_err(SQLBatchError::into_error)
448    }
449
450    fn sql_batch_observed(
451        &self,
452        statements: &[(&str, &[SQLParam])],
453        observe: impl Fn(&Engine, &mut SQLResult) -> Result<(), SQLError>,
454    ) -> Result<Vec<SQLResult>, SQLBatchError> {
455        self.transaction_with_error(
456            |engine| {
457                uqa_execution::statement::notifications::admit_sql_batch_diagnosed(
458                    engine.notification_subscriptions_required(),
459                    engine.parser_settings(),
460                    statements.iter().map(|(sql, _)| *sql),
461                    &engine.runtime.cancellation,
462                )?;
463                let mut results = Vec::with_capacity(statements.len());
464                for (index, (sql, params)) in statements.iter().enumerate() {
465                    let at_statement = |error| SQLBatchError::statement(error, index);
466                    let mut result = engine.sql(sql, params).map_err(at_statement)?;
467                    observe(engine, &mut result).map_err(at_statement)?;
468                    results.push(result);
469                }
470                Ok(results)
471            },
472            SQLBatchError::transaction,
473        )
474    }
475}