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, TransactionIntent, TransactionScope,
12};
13use uqa_sql::SQLBatchError;
14
15#[cfg(test)]
16#[path = "batch_diagnostic_tests.rs"]
17mod batch_diagnostic_tests;
18
19impl Engine {
20    /// 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`.
21    pub fn transaction<R>(
22        &self,
23        f: impl FnOnce(&Self) -> Result<R, SQLError>,
24    ) -> Result<R, SQLError> {
25        self.transaction_with_error(f, std::convert::identity)
26    }
27
28    pub(crate) fn transaction_with_error<R, E: std::fmt::Display>(
29        &self,
30        f: impl FnOnce(&Self) -> Result<R, E>,
31        map_transaction_error: impl Fn(SQLError) -> E,
32    ) -> Result<R, E> {
33        let _statement = self.lock_statement_gate();
34        let scope = TransactionScope::begin(self).map_err(&map_transaction_error)?;
35        self.run_transaction_scope(scope, f, map_transaction_error)
36    }
37
38    fn run_transaction_scope<R, E: std::fmt::Display>(
39        &self,
40        mut scope: TransactionScope<'_>,
41        f: impl FnOnce(&Self) -> Result<R, E>,
42        map_transaction_error: impl Fn(SQLError) -> E,
43    ) -> Result<R, E> {
44        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
45        match result {
46            Ok(Ok(value)) => {
47                scope.commit().map_err(&map_transaction_error)?;
48                Ok(value)
49            }
50            Ok(Err(err)) => {
51                if let Err(rollback_err) = scope.rollback() {
52                    return Err(map_transaction_error(Self::rollback_cleanup_error(&rollback_err, format!(
53                        "transaction rollback after error failed: {rollback_err}; original error: {err}"
54                    ))));
55                }
56                Err(err)
57            }
58            Err(payload) => match scope.rollback() {
59                Ok(()) => std::panic::resume_unwind(payload),
60                Err(rollback_err) => Err(map_transaction_error(Self::rollback_cleanup_error(
61                    &rollback_err,
62                    format!(
63                    "transaction rollback after panic failed: {rollback_err}; original panic: {}",
64                    panic_description(payload.as_ref())
65                ),
66                ))),
67            },
68        }
69    }
70
71    /// 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.
72    pub(crate) fn with_query_transaction_snapshot<R, E: std::fmt::Display>(
73        &self,
74        select_snapshot: bool,
75        read_only: bool,
76        query: impl FnOnce(&Self) -> Result<R, E>,
77        map_transaction_error: impl Fn(SQLError) -> E,
78    ) -> Result<R, E> {
79        if read_only && self.query_table_snapshots.is_some() {
80            // 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.
81            self.runtime
82                .cancellation
83                .check()
84                .map_err(SQLError::from)
85                .map_err(&map_transaction_error)?;
86            return query(self);
87        }
88        if self.transaction_depth() != 0 {
89            self.ensure_transaction_usable()
90                .map_err(&map_transaction_error)?;
91            return self.run_existing_transaction_operation(
92                || {
93                    self.runtime
94                        .cancellation
95                        .check()
96                        .map_err(SQLError::from)
97                        .map_err(&map_transaction_error)?;
98                    if select_snapshot {
99                        self.prepare_explicit_statement_snapshot(true)
100                            .map_err(&map_transaction_error)?;
101                        self.mark_transaction_snapshot_set();
102                    }
103                    query(self)
104                },
105                &map_transaction_error,
106            );
107        }
108        self.runtime
109            .cancellation
110            .check()
111            .map_err(SQLError::from)
112            .map_err(&map_transaction_error)?;
113        if self
114            .storage
115            .backend
116            .as_ref()
117            .map_or(read_only, |backend| backend.in_transaction())
118        {
119            return query(self);
120        }
121        let scope = TransactionScope::begin_implicit_statement(self, read_only)
122            .map_err(&map_transaction_error)?;
123        self.run_transaction_scope(
124            scope,
125            |engine| {
126                engine
127                    .prepare_explicit_statement_snapshot(true)
128                    .map_err(&map_transaction_error)?;
129                engine.mark_transaction_snapshot_set();
130                query(engine)
131            },
132            &map_transaction_error,
133        )
134    }
135
136    /// 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.
137    pub(crate) fn with_implicit_transaction<R>(
138        &self,
139        f: impl FnOnce(&Self) -> Result<R, SQLError>,
140    ) -> Result<R, SQLError> {
141        let _statement = self.lock_statement_gate();
142        if self.current_transaction_is_read_only() {
143            return Err(SQLError::Routine {
144                sqlstate: "25006".into(),
145                message: "cannot execute direct mutation in a read-only transaction".into(),
146            });
147        }
148        self.with_implicit_transaction_mutation(f)
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        if self.transaction_depth() != 0 {
156            self.ensure_transaction_usable()?;
157            return self.run_existing_transaction_operation(
158                || {
159                    self.prepare_explicit_transaction_writer()?;
160                    f(self)
161                },
162                std::convert::identity,
163            );
164        }
165        if self.storage.backend.is_none() {
166            return f(self);
167        }
168        self.transaction(|engine| {
169            engine.prepare_explicit_transaction_writer()?;
170            f(engine)
171        })
172    }
173
174    /// Definition changes need transaction-owned relation locks even for direct memory APIs. Defer physical writer admission until execution has acquired and revalidated those locks.
175    pub(crate) fn with_implicit_definition_transaction<R>(
176        &self,
177        f: impl FnOnce(&Self) -> Result<R, SQLError>,
178    ) -> Result<R, SQLError> {
179        let _statement = self.lock_statement_gate();
180        if self.current_transaction_is_read_only() {
181            return Err(SQLError::Routine {
182                sqlstate: "25006".into(),
183                message: "cannot execute direct mutation in a read-only transaction".into(),
184            });
185        }
186        if self.transaction_depth() != 0 {
187            self.ensure_transaction_usable()?;
188            self.run_existing_transaction_operation(
189                || {
190                    self.prepare_serializable_transaction_snapshot()?;
191                    let value = f(self)?;
192                    self.publish_catalog_constraint_tuples()?;
193                    Ok(value)
194                },
195                std::convert::identity,
196            )
197        } else {
198            self.transaction(|engine| {
199                engine.prepare_serializable_transaction_snapshot()?;
200                let value = f(engine)?;
201                engine.publish_catalog_constraint_tuples()?;
202                Ok(value)
203            })
204        }
205    }
206
207    /// Error-type-preserving counterpart for direct APIs whose public error
208    /// type is not [`SQLError`]. `map_transaction_error` is used only for
209    /// begin/commit/rollback infrastructure failures; an error returned by
210    /// `f` is passed through unchanged when rollback succeeds.
211    pub(crate) fn with_implicit_mapped_transaction<R, E>(
212        &self,
213        f: impl FnOnce(&Self) -> Result<R, E>,
214        map_transaction_error: impl Fn(SQLError) -> E,
215    ) -> Result<R, E>
216    where
217        E: std::fmt::Display,
218    {
219        let _statement = self.lock_statement_gate();
220        if self.current_transaction_is_read_only() {
221            return Err(map_transaction_error(SQLError::Routine {
222                sqlstate: "25006".into(),
223                message: "cannot execute direct mutation in a read-only transaction".into(),
224            }));
225        }
226        if self.transaction_depth() != 0 {
227            self.ensure_transaction_usable()
228                .map_err(&map_transaction_error)?;
229            return self.run_existing_transaction_operation(
230                || {
231                    self.prepare_explicit_transaction_writer()
232                        .map_err(&map_transaction_error)?;
233                    f(self)
234                },
235                &map_transaction_error,
236            );
237        }
238        if self.storage.backend.is_none() {
239            return f(self);
240        }
241        let mut scope = TransactionScope::begin(self).map_err(&map_transaction_error)?;
242        if let Err(error) = self.prepare_explicit_transaction_writer() {
243            let error = map_transaction_error(error);
244            return match scope.rollback() {
245                Ok(()) => Err(error),
246                Err(rollback_error) => Err(map_transaction_error(Self::rollback_cleanup_error(&rollback_error, format!(
247                    "rollback implicit engine transaction after promotion failure failed: {rollback_error}; original error: {error}"
248                )))),
249            };
250        }
251        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
252        match result {
253            Ok(Ok(value)) => {
254                scope.commit().map_err(&map_transaction_error)?;
255                Ok(value)
256            }
257            Ok(Err(error)) => match scope.rollback() {
258                Ok(()) => Err(error),
259                Err(rollback_error) => Err(map_transaction_error(Self::rollback_cleanup_error(&rollback_error, format!(
260                    "rollback implicit engine transaction failed: {rollback_error}; original error: {error}"
261                )))),
262            },
263            Err(payload) => match scope.rollback() {
264                Ok(()) => std::panic::resume_unwind(payload),
265                Err(rollback_error) => Err(map_transaction_error(Self::rollback_cleanup_error(&rollback_error, format!(
266                    "rollback implicit engine transaction after panic failed: {rollback_error}; original panic: {}",
267                    panic_description(payload.as_ref())
268                )))),
269            },
270        }
271    }
272
273    /// Storage-facing counterpart of [`Engine::with_implicit_transaction`].
274    /// The storage error is retained verbatim when rollback succeeds so API
275    /// callers can still classify the original backend failure.
276    pub(crate) fn with_implicit_storage_transaction<R>(
277        &self,
278        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
279    ) -> StorageBackendResult<R> {
280        if self.current_transaction_is_read_only() {
281            return Err(StorageBackendError::Other(
282                "cannot execute storage mutation in a read-only transaction".into(),
283            ));
284        }
285        self.with_implicit_storage_transaction_inner(false, true, f)
286    }
287
288    /// Complete direct schema publication within the same storage transaction and preserve its public error type.
289    pub(crate) fn with_implicit_storage_definition_transaction<R>(
290        &self,
291        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
292    ) -> StorageBackendResult<R> {
293        self.with_implicit_storage_transaction(|engine| {
294            let result = f(engine)?;
295            engine
296                .publish_catalog_constraint_tuples()
297                .map_err(|error| StorageBackendError::backend("constraint publication", error))?;
298            Ok(result)
299        })
300    }
301
302    /// 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.
303    pub(crate) fn with_read_only_compatible_storage_transaction<R>(
304        &self,
305        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
306    ) -> StorageBackendResult<R> {
307        self.with_storage_maintenance_scope(|engine| {
308            engine.prepare_storage_maintenance_writer()?;
309            f(engine)
310        })
311    }
312
313    /// 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.
314    pub(crate) fn with_storage_maintenance_scope<R>(
315        &self,
316        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
317    ) -> StorageBackendResult<R> {
318        self.with_implicit_storage_transaction_inner(true, false, f)
319    }
320
321    pub(crate) fn prepare_storage_maintenance_writer(&self) -> StorageBackendResult<()> {
322        self.prepare_explicit_transaction_writer()
323            .map_err(|error| StorageBackendError::backend("maintenance transaction", error))?;
324        if self.current_transaction_is_read_only() {
325            // SQL access remains read-only. Physical maintenance admission is retained until the transaction ends, including after savepoint undo.
326            for frame in self.session.transactions.lock().iter_mut() {
327                frame.intent = TransactionIntent::ReadWrite;
328            }
329        }
330        Ok(())
331    }
332
333    /// Automatic maintenance must release its relation locks instead of waiting behind a serialized writer that may need to upgrade those same locks.
334    pub(crate) fn try_prepare_storage_maintenance_writer(&self) -> StorageBackendResult<bool> {
335        let mark = self
336            .session
337            .transactions
338            .lock()
339            .first()
340            .filter(|frame| frame.backend_mode == BackendTransactionMode::Deferred)
341            .map(|frame| frame.begin_lock_mark);
342        if let Some(mark) = mark {
343            let admitted = self
344                .row_locks
345                .try_acquire_relation(
346                    self.session_id,
347                    self.row_locks.backend_writer_key(),
348                    crate::row_locks::RelationLockMode::AccessExclusive,
349                    mark,
350                    &self.runtime.cancellation,
351                )
352                .map_err(|error| {
353                    StorageBackendError::backend("maintenance writer admission", error)
354                })?;
355            if !admitted {
356                return Ok(false);
357            }
358        }
359        self.prepare_storage_maintenance_writer()?;
360        Ok(true)
361    }
362
363    fn with_implicit_storage_transaction_inner<R>(
364        &self,
365        maintenance_can_override_default_read_only: bool,
366        promote_writer: bool,
367        f: impl FnOnce(&Self) -> StorageBackendResult<R>,
368    ) -> StorageBackendResult<R> {
369        let _statement = self.lock_statement_gate();
370        if self.transaction_depth() != 0 {
371            self.ensure_transaction_usable()
372                .map_err(|error| StorageBackendError::backend("storage transaction", error))?;
373            return self.run_existing_transaction_operation(
374                || {
375                    self.prepare_serializable_transaction_snapshot()
376                        .map_err(|error| {
377                            StorageBackendError::backend("maintenance snapshot", error)
378                        })?;
379                    if promote_writer {
380                        self.prepare_explicit_transaction_writer()
381                            .map_err(|error| {
382                                StorageBackendError::backend("promote storage transaction", error)
383                            })?;
384                    }
385                    f(self)
386                },
387                |error| StorageBackendError::backend("transaction abort", error),
388            );
389        }
390        let mut scope = TransactionScope::begin(self).map_err(|error| {
391            StorageBackendError::backend("begin implicit storage transaction", error)
392        })?;
393        if maintenance_can_override_default_read_only {
394            if let Some(frame) = self.session.transactions.lock().last_mut() {
395                frame.intent = TransactionIntent::ReadWrite;
396                frame.characteristics.read_only = false;
397            }
398        }
399        let preparation = self
400            .prepare_serializable_transaction_snapshot()
401            .and_then(|()| {
402                promote_writer
403                    .then(|| self.prepare_explicit_transaction_writer())
404                    .transpose()
405                    .map(|_| ())
406            });
407        if let Err(error) = preparation {
408            let error = StorageBackendError::backend("prepare implicit storage transaction", error);
409            return match scope.rollback() {
410                Ok(()) => Err(error),
411                Err(rollback_error) => Err(StorageBackendError::backend("rollback implicit storage transaction", Self::rollback_cleanup_error(&rollback_error, format!(
412                    "rollback implicit engine transaction after promotion failure failed: {rollback_error}; original error: {error}"
413                )))),
414            };
415        }
416        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
417        match result {
418            Ok(Ok(value)) => {
419                scope.commit().map_err(|error| {
420                    StorageBackendError::backend("commit implicit storage transaction", error)
421                })?;
422                Ok(value)
423            }
424            Ok(Err(error)) => match scope.rollback() {
425                Ok(()) => Err(error),
426                Err(rollback_error) => Err(StorageBackendError::backend("rollback implicit storage transaction", Self::rollback_cleanup_error(&rollback_error, format!(
427                    "rollback implicit engine transaction failed: {rollback_error}; original error: {error}"
428                )))),
429            },
430            Err(payload) => match scope.rollback() {
431                Ok(()) => std::panic::resume_unwind(payload),
432                Err(rollback_error) => Err(StorageBackendError::backend("rollback implicit storage transaction", Self::rollback_cleanup_error(&rollback_error, format!(
433                    "rollback implicit engine transaction after panic failed: {rollback_error}; original panic: {}",
434                    panic_description(payload.as_ref())
435                )))),
436            },
437        }
438    }
439
440    pub(crate) fn with_implicit_string_transaction<R>(
441        &self,
442        f: impl FnOnce(&Self) -> Result<R, String>,
443    ) -> Result<R, String> {
444        let _statement = self.lock_statement_gate();
445        if self.transaction_depth() != 0 {
446            self.ensure_transaction_usable()
447                .map_err(|error| error.to_string())?;
448            return self.run_existing_transaction_operation(
449                || {
450                    self.prepare_explicit_transaction_writer()
451                        .map_err(|error| {
452                            format!("promote explicit engine transaction failed: {error}")
453                        })?;
454                    f(self)
455                },
456                |error| error.to_string(),
457            );
458        }
459        let mut scope = TransactionScope::begin(self)
460            .map_err(|error| format!("begin implicit engine transaction failed: {error}"))?;
461        if let Err(error) = self.prepare_explicit_transaction_writer() {
462            let error = format!("promote implicit engine transaction failed: {error}");
463            return match scope.rollback() {
464                Ok(()) => Err(error),
465                Err(rollback_error) => Err(format!(
466                    "rollback implicit engine transaction after promotion failure failed: {rollback_error}; original error: {error}"
467                )),
468            };
469        }
470        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self)));
471        match result {
472            Ok(Ok(value)) => {
473                scope
474                    .commit()
475                    .map_err(|error| format!("commit implicit engine transaction failed: {error}"))?;
476                Ok(value)
477            }
478            Ok(Err(error)) => match scope.rollback() {
479                Ok(()) => Err(error),
480                Err(rollback_error) => Err(format!(
481                    "rollback implicit engine transaction failed: {rollback_error}; original error: {error}"
482                )),
483            },
484            Err(payload) => match scope.rollback() {
485                Ok(()) => std::panic::resume_unwind(payload),
486                Err(rollback_error) => Err(format!(
487                    "rollback implicit engine transaction after panic failed: {rollback_error}; original panic: {}",
488                    panic_description(payload.as_ref())
489                )),
490            },
491        }
492    }
493
494    /// Execute multiple SQL statements inside one engine transaction.
495    pub fn sql_batch(
496        &self,
497        statements: &[(&str, &[SQLParam])],
498    ) -> Result<Vec<SQLResult>, SQLError> {
499        self.sql_batch_diagnosed(statements)
500            .map_err(SQLBatchError::into_error)
501    }
502
503    /// Execute the same atomic batch while retaining the zero-based failing member.
504    /// Transaction-boundary failures carry no member; no statement is retried.
505    pub fn sql_batch_diagnosed(
506        &self,
507        statements: &[(&str, &[SQLParam])],
508    ) -> Result<Vec<SQLResult>, SQLBatchError> {
509        self.sql_batch_observed(statements, |_, _| Ok(()))
510    }
511
512    /// 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.
513    pub fn sql_batch_with_labels(
514        &self,
515        statements: &[(&str, &[SQLParam])],
516    ) -> Result<Vec<SQLResult>, SQLError> {
517        self.sql_batch_observed(statements, Engine::render_enum_labels)
518            .map_err(SQLBatchError::into_error)
519    }
520
521    fn sql_batch_observed(
522        &self,
523        statements: &[(&str, &[SQLParam])],
524        observe: impl Fn(&Engine, &mut SQLResult) -> Result<(), SQLError>,
525    ) -> Result<Vec<SQLResult>, SQLBatchError> {
526        self.transaction_with_error(
527            |engine| {
528                uqa_execution::statement::notifications::admit_sql_batch_diagnosed(
529                    engine.notification_subscriptions_required(),
530                    engine.parser_settings(),
531                    statements.iter().map(|(sql, _)| *sql),
532                    &engine.runtime.cancellation,
533                )?;
534                let mut results = Vec::with_capacity(statements.len());
535                for (index, (sql, params)) in statements.iter().enumerate() {
536                    let at_statement = |error| SQLBatchError::statement(error, index);
537                    let mut result = engine.sql(sql, params).map_err(at_statement)?;
538                    observe(engine, &mut result).map_err(at_statement)?;
539                    results.push(result);
540                }
541                Ok(results)
542            },
543            SQLBatchError::transaction,
544        )
545    }
546}