Skip to main content

uqa_engine/transactions/
row_locks_session.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Session-level integration between the SQL transaction stack and the row-lock manager: typed-mutation locking, statement-scoped recheck contexts, and change publication for tuple-local rechecks.
8
9use super::{
10    panic_description, BackendTransactionMode, Engine, SQLError, TransactionIntent,
11    TransactionRowChange,
12};
13
14impl Engine {
15    fn ensure_row_mutation_allowed(&self, table: &str) -> Result<(), SQLError> {
16        if self.current_transaction_is_read_only()
17            && self
18                .table_persistence(table)
19                .map_err(|error| {
20                    SQLError::Internal(format!(
21                        "resolve read-only row mutation target `{table}`: {error}"
22                    ))
23                })?
24                .is_some_and(|persistence| {
25                    persistence != uqa_sql::ast::RelationPersistence::Temporary
26                })
27        {
28            return Err(SQLError::Routine {
29                sqlstate: "25006".into(),
30                message: "cannot execute row mutation in a read-only transaction".into(),
31            });
32        }
33        Ok(())
34    }
35
36    /// Keep the row mutation transaction boundary after SQL has acquired its chosen tuple-lock strength. Existing temporary rows retain their read-only transaction permission without taking a stronger lock.
37    pub(crate) fn with_prepared_row_write_transaction<R>(
38        &self,
39        table: &str,
40        f: impl FnOnce(&Self) -> Result<R, SQLError>,
41    ) -> Result<R, SQLError> {
42        let _statement = self.lock_statement_gate();
43        self.ensure_row_mutation_allowed(table)?;
44        self.with_implicit_transaction_mutation(f)
45    }
46
47    /// Run one typed row mutation with the same relation/tuple locking order as SQL DML: logical locks first, backend-writer promotion second. This prevents typed APIs from bypassing `SELECT ... FOR UPDATE` and avoids a writer/row-lock inversion while waiting for another transaction.
48    pub(crate) fn with_implicit_row_write_transaction<R>(
49        &self,
50        table: &str,
51        doc_id: uqa_core::DocId,
52        strength: uqa_sql::ast::LockStrength,
53        f: impl FnOnce(&Self) -> Result<R, SQLError>,
54    ) -> Result<R, SQLError> {
55        self.row_write_transaction(table, Some((doc_id, strength)), true, f)
56    }
57
58    /// Run a typed row write whose generated columns and expression-index keys evaluate SQL expressions. The evaluation runs under the session's statement thread context, entered inside the row-write transaction so its transaction clock is the start of any implicit transaction the write opens.
59    pub(crate) fn with_evaluating_row_write_transaction<R>(
60        &self,
61        table: &str,
62        doc_id: uqa_core::DocId,
63        strength: uqa_sql::ast::LockStrength,
64        f: impl FnOnce(&Self) -> Result<R, SQLError>,
65    ) -> Result<R, SQLError> {
66        self.with_implicit_row_write_transaction(table, doc_id, strength, |engine| {
67            let _statement_thread = engine.statement_thread_context().enter();
68            f(engine)
69        })
70    }
71
72    /// Run the write of an inserted row. One that may replace a row locks it as any typed row mutation does.
73    ///
74    /// A new row takes no lock of its own. No other transaction can address its identity before this one commits: a supplied identity is a unique key whose value this transaction has reserved, a generated one was reserved for the row, and a versioned transaction keeps the row private until it commits. `PostgreSQL` likewise locks no tuple it inserts and makes no session wait for a row that session cannot see. The row may still be written over the revision a deleted row left, which the write must expect as it stands now, so the storage target is refreshed unless the identity was never used.
75    pub(crate) fn with_inserted_row_write_transaction<R>(
76        &self,
77        table: &str,
78        doc_id: uqa_core::DocId,
79        inserted: uqa_execution::mutation::publication::InsertedIdentity,
80        f: impl FnOnce(&Self) -> Result<R, SQLError>,
81    ) -> Result<R, SQLError> {
82        if inserted.is_vacant() && self.versioned_backend_transactions() {
83            return self.row_write_transaction(table, None, !inserted.is_unused(), f);
84        }
85        self.with_implicit_row_write_transaction(
86            table,
87            doc_id,
88            uqa_sql::ast::LockStrength::ForUpdate,
89            f,
90        )
91    }
92
93    /// `row` is the tuple to lock before the write, and `refresh` says whether the write needs the latest committed state, as it does after a lock that may have waited for a writer that has since committed.
94    fn row_write_transaction<R>(
95        &self,
96        table: &str,
97        row: Option<(uqa_core::DocId, uqa_sql::ast::LockStrength)>,
98        refresh: bool,
99        f: impl FnOnce(&Self) -> Result<R, SQLError>,
100    ) -> Result<R, SQLError> {
101        let _statement = self.lock_statement_gate();
102        self.ensure_row_mutation_allowed(table)?;
103        if self.storage.backend.is_none() && self.transaction_depth() == 0 {
104            return f(self);
105        }
106        if self.transaction_depth() != 0 {
107            self.ensure_transaction_usable()?;
108        }
109
110        let started = self.transaction_depth() == 0;
111        if started {
112            self.begin_implicit_statement_transaction(false)?;
113        }
114        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
115            self.prepare_serializable_transaction_snapshot()?;
116            self.lock_relation(table, crate::row_locks::RelationLockMode::RowExclusive)?;
117            if let Some((doc_id, strength)) = row {
118                match self.lock_row(
119                    table,
120                    doc_id,
121                    strength,
122                    uqa_sql::ast::LockWait::Block,
123                    table,
124                )? {
125                    crate::row_locks::LockAcquire::Granted { .. } => {}
126                    crate::row_locks::LockAcquire::Skipped => {
127                        return Err(SQLError::Internal(
128                            "blocking typed row mutation unexpectedly skipped a row".into(),
129                        ));
130                    }
131                }
132            }
133            if refresh {
134                self.prepare_explicit_transaction_writer()?;
135            } else {
136                self.prepare_unrefreshed_transaction_writer()?;
137            }
138            f(self)
139        }));
140
141        if !started {
142            return self.finish_existing_transaction_operation(result, std::convert::identity);
143        }
144        match result {
145            Ok(Ok(value)) => {
146                self.commit()?;
147                Ok(value)
148            }
149            Ok(Err(error)) => match self.rollback() {
150                Ok(()) => Err(error),
151                Err(rollback_error) => Err(Self::rollback_cleanup_error(&rollback_error, format!(
152                    "typed row mutation failed: {error}; rollback also failed: {rollback_error}"
153                ))),
154            },
155            Err(payload) => match self.rollback() {
156                Ok(()) => std::panic::resume_unwind(payload),
157                Err(rollback_error) => Err(Self::rollback_cleanup_error(&rollback_error, format!(
158                    "typed row mutation rollback after panic failed: {rollback_error}; original panic: {}",
159                    panic_description(payload.as_ref())
160                ))),
161            },
162        }
163    }
164
165    fn row_lock_table_name(&self, table: &str) -> Result<String, SQLError> {
166        self.try_resolve_table_name(table)
167            .map_err(|error| {
168                SQLError::Internal(format!("resolve row-lock table `{table}`: {error}"))
169            })
170            .map(|resolved| resolved.unwrap_or_else(|| table.to_string()))
171    }
172
173    pub(crate) fn row_lock_change_requires_recheck(&self) -> Result<bool, SQLError> {
174        let Some(backend) = self.storage.backend.as_ref() else {
175            return Ok(true);
176        };
177        if self.storage.provider.is_none() {
178            return Ok(false);
179        }
180        if backend.transaction_model().is_versioned() {
181            return Ok(true);
182        }
183        let stack = self.session.transactions.lock();
184        let deferred_reader = stack.first().is_some_and(|frame| {
185            frame.intent == TransactionIntent::ReadOnly
186                || frame.backend_mode == BackendTransactionMode::Deferred
187        });
188        drop(stack);
189        if !deferred_reader {
190            return Ok(false);
191        }
192        backend
193            .transaction_has_written()
194            .map(|written| !written)
195            .map_err(|error| Self::storage_tx_error("inspect row-lock recheck snapshot", &error))
196    }
197
198    pub(crate) fn lock_row(
199        &self,
200        table: &str,
201        doc_id: uqa_core::DocId,
202        strength: uqa_sql::ast::LockStrength,
203        wait: uqa_sql::ast::LockWait,
204        display_name: &str,
205    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
206        let canonical = self.row_lock_table_name(table)?;
207        let key = crate::row_locks::RowLockKey {
208            table: self.row_locks.table_key(&canonical),
209            doc_id,
210        };
211        self.row_locks.acquire(&crate::row_locks::LockRequest {
212            session_id: self.session_id,
213            key,
214            strength,
215            mark: self.current_lock_mark(),
216            wait,
217            cancel: &self.runtime.cancellation,
218            relation: display_name,
219        })
220    }
221
222    /// Refresh a named parameter after obtaining its transaction-retained logical lock. Execution workers already belong to the parent command, so this adapter must not reenter its thread-owned statement gate.
223    pub(crate) fn lock_scoring_parameter_write(&self, name: &str) -> Result<(), SQLError> {
224        let Some(backend) = self
225            .storage
226            .backend
227            .as_ref()
228            .filter(|backend| backend.transaction_model().is_versioned())
229        else {
230            return Ok(());
231        };
232        if self.transaction_depth() == 0 {
233            return Err(SQLError::Internal(
234                "scoring parameter writes require an active transaction".into(),
235            ));
236        }
237        self.row_locks.acquire(&crate::row_locks::LockRequest {
238            session_id: self.session_id,
239            key: crate::row_locks::RowLockKey {
240                table: self.row_locks.scoring_parameters_key(name),
241                doc_id: 0,
242            },
243            strength: uqa_sql::ast::LockStrength::ForUpdate,
244            mark: self.current_lock_mark(),
245            wait: uqa_sql::ast::LockWait::Block,
246            cancel: &self.runtime.cancellation,
247            relation: name,
248        })?;
249        backend
250            .refresh_transaction_snapshot(&self.runtime.cancellation)
251            .map_err(|error| Self::storage_tx_error("refresh scoring parameters", &error))
252    }
253
254    pub(crate) fn reserve_document_id_candidate(
255        &self,
256        table: &str,
257        doc_id: uqa_core::DocId,
258    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
259        let canonical = self.row_lock_table_name(table)?;
260        self.row_locks.acquire(&crate::row_locks::LockRequest {
261            session_id: self.session_id,
262            key: crate::row_locks::RowLockKey {
263                table: self.row_locks.document_identity_key(&canonical),
264                doc_id,
265            },
266            strength: uqa_sql::ast::LockStrength::ForUpdate,
267            mark: self.current_lock_mark(),
268            wait: uqa_sql::ast::LockWait::SkipLocked,
269            cancel: &self.runtime.cancellation,
270            relation: table,
271        })
272    }
273
274    pub(crate) fn lock_key_reservation(
275        &self,
276        digest: [u8; 32],
277        display_name: &str,
278    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
279        let retained = self.row_locks.retain_key_reservation(digest);
280        let key = crate::row_locks::RowLockKey {
281            table: retained.table_key(),
282            doc_id: 0,
283        };
284        self.row_locks.acquire(&crate::row_locks::LockRequest {
285            session_id: self.session_id,
286            key,
287            strength: uqa_sql::ast::LockStrength::ForUpdate,
288            mark: self.current_lock_mark(),
289            wait: uqa_sql::ast::LockWait::Block,
290            cancel: &self.runtime.cancellation,
291            relation: display_name,
292        })
293    }
294
295    pub(crate) fn lock_key_reservations(
296        &self,
297        keys: &[[u8; 32]],
298        display_name: &str,
299    ) -> Result<Vec<crate::row_locks::LockAcquire>, SQLError> {
300        let mark = self.current_lock_mark();
301        let retained = keys
302            .iter()
303            .map(|key| self.row_locks.retain_key_reservation(*key))
304            .collect::<Vec<_>>();
305        let requests = retained
306            .iter()
307            .map(|identity| crate::row_locks::LockRequest {
308                session_id: self.session_id,
309                key: crate::row_locks::RowLockKey {
310                    table: identity.table_key(),
311                    doc_id: 0,
312                },
313                strength: uqa_sql::ast::LockStrength::ForUpdate,
314                mark,
315                wait: uqa_sql::ast::LockWait::Block,
316                cancel: &self.runtime.cancellation,
317                relation: display_name,
318            })
319            .collect::<Vec<_>>();
320        self.row_locks.acquire_batch(&requests)
321    }
322
323    pub(crate) fn lock_relation(
324        &self,
325        table: &str,
326        mode: crate::row_locks::RelationLockMode,
327    ) -> Result<(), SQLError> {
328        let canonical = self.row_lock_table_name(table)?;
329        self.row_locks.acquire_relation(
330            self.session_id,
331            self.row_locks.table_key(&canonical),
332            mode,
333            self.current_lock_mark(),
334            &self.runtime.cancellation,
335        )
336    }
337
338    pub(crate) fn temporary_relation_lock(
339        &self,
340        table: &str,
341        mode: crate::row_locks::RelationLockMode,
342    ) -> Result<crate::row_locks::ScopedRelationLock<'_>, SQLError> {
343        let canonical = self.row_lock_table_name(table)?;
344        self.prepare_transaction_lock_wait()?;
345        self.row_locks.acquire_scoped_relation(
346            self.session_id,
347            self.row_locks.table_key(&canonical),
348            mode,
349            self.temporary_relation_lock_marks()?,
350            &self.runtime.cancellation,
351        )
352    }
353
354    /// Whether the open transaction of this session already changed or rewrote the row itself. Such a row's current image is authoritative for this session, so cross-process verification must not replace it with the older committed image.
355    pub(crate) fn row_changed_in_open_transaction(
356        &self,
357        table: &str,
358        doc_id: uqa_core::DocId,
359    ) -> Result<bool, SQLError> {
360        let canonical = self.row_lock_table_name(table)?;
361        let key = crate::row_locks::RowLockKey {
362            table: self.row_locks.table_key(&canonical),
363            doc_id,
364        };
365        Ok(self.session.transactions.lock().iter().any(|frame| {
366            frame.row_changes.iter().any(|change| {
367                change.pending.key == key
368                    || matches!(
369                        change.pending.kind,
370                        crate::row_locks::PendingRowChangeKind::Rewrite(successor)
371                            if successor == key
372                    )
373            })
374        }))
375    }
376
377    /// The row identity a committed primary-key rewrite moved `doc_id` to, following chained rewrites to the final identity. `None` when the row keeps its identity in the latest committed state visible to the lock manager. Rewrites are recorded only while a lock or observer keeps them alive, which covers every DML statement waiting on the row.
378    pub(crate) fn committed_row_successor(
379        &self,
380        table: &str,
381        doc_id: uqa_core::DocId,
382    ) -> Result<crate::row_locks::RowChangeTarget, SQLError> {
383        let canonical = self.row_lock_table_name(table)?;
384        self.row_locks.row_successor_after(
385            &canonical,
386            doc_id,
387            &self.row_lock_snapshot_change_baseline()?,
388        )
389    }
390
391    pub(crate) fn committed_physical_row_successor(
392        &self,
393        table: &str,
394        doc_id: uqa_core::DocId,
395    ) -> Result<crate::row_locks::PhysicalRowChangeTarget, SQLError> {
396        let canonical = self.row_lock_table_name(table)?;
397        self.row_locks.physical_row_successor_after(
398            &canonical,
399            doc_id,
400            &self.row_lock_snapshot_change_baseline()?,
401        )
402    }
403
404    pub(crate) fn row_lock_table_for_hash(&self, table_hash: u64) -> Result<String, SQLError> {
405        let tables = self.storage.tables.read();
406        let mut matches = tables
407            .keys()
408            .map(uqa_storage::RelationIdentity::qualified_name)
409            .filter(|table| {
410                crate::row_locks::RowLockManager::stable_table_hash(table) == table_hash
411            });
412        let table = matches.next().ok_or_else(|| {
413            SQLError::Internal(format!(
414                "row-change successor refers to unknown relation hash {table_hash}"
415            ))
416        })?;
417        if matches.next().is_some() {
418            return Err(SQLError::Internal(format!(
419                "row-change successor relation hash {table_hash} is ambiguous"
420            )));
421        }
422        Ok(table)
423    }
424
425    fn deferred_foreign_key_checks_for_row(
426        &self,
427        table: &str,
428        row: crate::row_locks::RowLockKey,
429        rewrite: Option<(&crate::Document, &crate::Document)>,
430    ) -> Result<Vec<crate::DeferredForeignKeyCheck>, SQLError> {
431        let firing_relation =
432            crate::RelationIdentity::from_legacy_name(table).map_err(|error| {
433                SQLError::Internal(format!(
434                    "decode deferred foreign-key firing relation '{table}': {error}"
435                ))
436            })?;
437        let foreign_keys = self.foreign_keys_in_execution(table).map_err(|error| {
438            SQLError::Internal(format!(
439                "read deferred foreign keys for table `{table}`: {error}"
440            ))
441        })?;
442        let mut checks = Vec::new();
443        for foreign_key in foreign_keys {
444            if rewrite.is_some_and(|(old_document, new_document)| {
445                foreign_key.local_columns.iter().all(|column| {
446                    old_document
447                        .get(column)
448                        .cloned()
449                        .unwrap_or(crate::Value::Null)
450                        == new_document
451                            .get(column)
452                            .cloned()
453                            .unwrap_or(crate::Value::Null)
454                })
455            }) {
456                continue;
457            }
458            if foreign_key.enforced && self.foreign_key_is_deferred(table, &foreign_key)? {
459                checks.push(crate::DeferredForeignKeyCheck {
460                    constraint: self.foreign_key_constraint_identity(table, &foreign_key)?,
461                    firing_relation: firing_relation.clone(),
462                    row: Some(row),
463                    referenced: false,
464                });
465            }
466        }
467        Ok(checks)
468    }
469
470    fn note_row_change(
471        &self,
472        table: &str,
473        doc_id: uqa_core::DocId,
474        kind: crate::row_locks::PendingRowChangeKind,
475    ) -> Result<(), SQLError> {
476        let canonical = self.row_lock_table_name(table)?;
477        let key = crate::row_locks::RowLockKey {
478            table: self.row_locks.table_key(&canonical),
479            doc_id,
480        };
481        let source_generation = self.require_table(&canonical)?.storage_generation();
482        let mut stack = self.session.transactions.lock();
483        let pending = crate::row_locks::PendingRowChange { key, kind };
484        if let Some(frame) = stack.last_mut() {
485            let change = TransactionRowChange {
486                pending,
487                source_generation,
488                successor_generation: None,
489                query_origin: self
490                    .session_execution_view()
491                    .transaction_snapshot_identity(),
492            };
493            frame.row_changes.push(change);
494            self.follow_row_change(&mut stack, &change)
495        } else {
496            drop(stack);
497            let publication = self
498                .row_locks
499                .begin_change_publication(&self.runtime.cancellation)?;
500            let result = self
501                .row_locks
502                .publish_row_changes(self.session_id, [pending]);
503            drop(publication);
504            result
505        }
506    }
507
508    pub(crate) fn note_row_inserted(
509        &self,
510        table: &str,
511        doc_id: uqa_core::DocId,
512    ) -> Result<(), SQLError> {
513        self.note_row_change(
514            table,
515            doc_id,
516            crate::row_locks::PendingRowChangeKind::Insert,
517        )
518    }
519
520    pub(crate) fn note_row_changed(
521        &self,
522        table: &str,
523        doc_id: uqa_core::DocId,
524    ) -> Result<(), SQLError> {
525        self.note_row_change(
526            table,
527            doc_id,
528            crate::row_locks::PendingRowChangeKind::Update,
529        )
530    }
531
532    pub(crate) fn note_row_deleted(
533        &self,
534        table: &str,
535        doc_id: uqa_core::DocId,
536    ) -> Result<(), SQLError> {
537        self.note_row_change(
538            table,
539            doc_id,
540            crate::row_locks::PendingRowChangeKind::Delete,
541        )
542    }
543
544    pub(crate) fn defer_inserted_foreign_key_checks(
545        &self,
546        table: &str,
547        doc_id: uqa_core::DocId,
548    ) -> Result<(), SQLError> {
549        if self.session.transactions.lock().is_empty() {
550            return Ok(());
551        }
552        let canonical = self.row_lock_table_name(table)?;
553        let row = crate::row_locks::RowLockKey {
554            table: self.row_locks.table_key(&canonical),
555            doc_id,
556        };
557        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, None)?;
558        if let Some(frame) = self.session.transactions.lock().last_mut() {
559            frame.deferred_foreign_key_checks.extend(checks);
560        }
561        Ok(())
562    }
563
564    pub(crate) fn defer_rewritten_foreign_key_checks(
565        &self,
566        table: &str,
567        doc_id: uqa_core::DocId,
568        old_document: Option<&crate::Document>,
569        new_document: &crate::Document,
570    ) -> Result<(), SQLError> {
571        if self.session.transactions.lock().is_empty() {
572            return Ok(());
573        }
574        let canonical = self.row_lock_table_name(table)?;
575        let row = crate::row_locks::RowLockKey {
576            table: self.row_locks.table_key(&canonical),
577            doc_id,
578        };
579        let rewrite = old_document.map(|old_document| (old_document, new_document));
580        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, rewrite)?;
581        if let Some(frame) = self.session.transactions.lock().last_mut() {
582            frame.deferred_foreign_key_checks.extend(checks);
583        }
584        Ok(())
585    }
586
587    /// Defer the check of a referencing row that a change to a referenced row fired, under the constraint whose deferral governs it.
588    pub(crate) fn defer_foreign_key_check(
589        &self,
590        event: super::DeferredReferencedKey<'_>,
591        row_table: &str,
592        doc_id: uqa_core::DocId,
593    ) -> Result<(), SQLError> {
594        let canonical_row_table = self.row_lock_table_name(row_table)?;
595        let check = crate::DeferredForeignKeyCheck {
596            constraint: self.referenced_key_constraint_identity(&event)?,
597            firing_relation: self.deferred_firing_relation(event.firing_table)?,
598            row: Some(crate::row_locks::RowLockKey {
599                table: self.row_locks.table_key(&canonical_row_table),
600                doc_id,
601            }),
602            referenced: true,
603        };
604        let mut stack = self.session.transactions.lock();
605        let frame = stack.last_mut().ok_or_else(|| {
606            SQLError::Internal("deferred foreign-key check outside a transaction".into())
607        })?;
608        frame.deferred_foreign_key_checks.push(check);
609        Ok(())
610    }
611
612    fn deferred_firing_relation(
613        &self,
614        firing_table: &str,
615    ) -> Result<crate::RelationIdentity, SQLError> {
616        let canonical_firing_table = self.row_lock_table_name(firing_table)?;
617        crate::RelationIdentity::from_legacy_name(&canonical_firing_table).map_err(|error| {
618            SQLError::Internal(format!(
619                "decode deferred foreign-key firing relation '{canonical_firing_table}': {error}"
620            ))
621        })
622    }
623
624    pub(crate) fn defer_foreign_key_parent_event(
625        &self,
626        event: super::DeferredReferencedKey<'_>,
627    ) -> Result<(), SQLError> {
628        let check = crate::DeferredForeignKeyCheck {
629            constraint: self.referenced_key_constraint_identity(&event)?,
630            firing_relation: self.deferred_firing_relation(event.firing_table)?,
631            row: None,
632            referenced: true,
633        };
634        let mut stack = self.session.transactions.lock();
635        let frame = stack.last_mut().ok_or_else(|| {
636            SQLError::Internal("deferred foreign-key event outside a transaction".into())
637        })?;
638        frame.deferred_foreign_key_checks.push(check);
639        Ok(())
640    }
641
642    pub(crate) fn note_row_rewritten_between_tables(
643        &self,
644        old_table: &str,
645        old_doc_id: uqa_core::DocId,
646        new_table: &str,
647        new_doc_id: uqa_core::DocId,
648    ) -> Result<(), SQLError> {
649        let old_table = self.row_lock_table_name(old_table)?;
650        let new_table = self.row_lock_table_name(new_table)?;
651        let old = crate::row_locks::RowLockKey {
652            table: self.row_locks.table_key(&old_table),
653            doc_id: old_doc_id,
654        };
655        let new = crate::row_locks::RowLockKey {
656            table: self.row_locks.table_key(&new_table),
657            doc_id: new_doc_id,
658        };
659        let source_generation = self.require_table(&old_table)?.storage_generation();
660        let successor_generation = self.require_table(&new_table)?.storage_generation();
661        let mut stack = self.session.transactions.lock();
662        let pending = crate::row_locks::PendingRowChange {
663            key: old,
664            kind: crate::row_locks::PendingRowChangeKind::Rewrite(new),
665        };
666        if let Some(frame) = stack.last_mut() {
667            for check in &mut frame.deferred_foreign_key_checks {
668                if check.row == Some(old) {
669                    check.row = Some(new);
670                }
671            }
672            let change = TransactionRowChange {
673                pending,
674                source_generation,
675                successor_generation: Some(successor_generation),
676                query_origin: self
677                    .session_execution_view()
678                    .transaction_snapshot_identity(),
679            };
680            frame.row_changes.push(change);
681            self.follow_row_change(&mut stack, &change)
682        } else {
683            drop(stack);
684            let publication = self
685                .row_locks
686                .begin_change_publication(&self.runtime.cancellation)?;
687            let result = self
688                .row_locks
689                .publish_row_changes(self.session_id, [pending]);
690            drop(publication);
691            result
692        }
693    }
694
695    pub(crate) fn row_lock_manager(&self) -> std::sync::Arc<crate::row_locks::RowLockManager> {
696        std::sync::Arc::clone(&self.row_locks)
697    }
698
699    /// Mark one in-flight SQL statement so every locking scope it executes, including scopes inside query-bearing commands, prepared execution, `EXPLAIN ANALYZE`, and DML sources, shares one row-lock recheck context. Host-callback statements nested inside another statement push their own frame.
700    pub(crate) fn begin_row_lock_statement(&self) -> RowLockStatementScope<'_> {
701        self.session.row_lock_statements.lock().push(None);
702        RowLockStatementScope { engine: self }
703    }
704
705    /// The active statement's shared row-lock recheck context, created on first use with the statement snapshot's change epoch as its recheck baseline. A direct engine call outside any SQL statement owns an ephemeral context with the same baseline semantics.
706    pub(crate) fn statement_row_lock_cache(
707        &self,
708    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
709    {
710        let budget_bytes = self.work_mem_bytes()?;
711        let baseline = self.row_lock_snapshot_change_baseline()?;
712        let mut statements = self.session.row_lock_statements.lock();
713        let Some(slot) = statements.last_mut() else {
714            drop(statements);
715            return Ok(std::sync::Arc::new(
716                uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
717                    budget_bytes,
718                    self.row_lock_manager(),
719                    baseline,
720                ),
721            ));
722        };
723        if let Some(cache) = slot.as_ref() {
724            return Ok(std::sync::Arc::clone(cache));
725        }
726        let cache = std::sync::Arc::new(
727            uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
728                budget_bytes,
729                self.row_lock_manager(),
730                baseline,
731            ),
732        );
733        *slot = Some(std::sync::Arc::clone(&cache));
734        Ok(cache)
735    }
736
737    pub(crate) fn row_lock_snapshot_change_baseline(
738        &self,
739    ) -> Result<crate::row_locks::RowChangeBaseline, SQLError> {
740        if let Some(frame) = self.session.transactions.lock().first() {
741            return Ok(frame.snapshot_change_baseline.clone());
742        }
743        self.row_locks
744            .begin_change_snapshot(&self.runtime.cancellation)?
745            .baseline()
746    }
747
748    pub(crate) fn update_statement_row_lock_baseline(
749        &self,
750        baseline: crate::row_locks::RowChangeBaseline,
751    ) {
752        if let Some(Some(cache)) = self.session.row_lock_statements.lock().last() {
753            cache.set_snapshot_baseline(baseline);
754        }
755    }
756
757    pub(crate) fn rollback_row_lock_acquisition(
758        &self,
759        acquisition: crate::row_locks::RowLockAcquisition,
760    ) {
761        self.row_locks.rollback_acquisition(acquisition);
762    }
763}
764
765/// RAII frame for one in-flight SQL statement's shared row-lock recheck context. Dropping the frame releases the statement's change observation so the lock manager can prune retained row-change versions.
766pub(crate) struct RowLockStatementScope<'engine> {
767    engine: &'engine Engine,
768}
769
770impl uqa_execution::statement::batch::context::RowLockStatementGuard for RowLockStatementScope<'_> {}
771
772impl uqa_execution::statement::batch::context::BatchRowLocks for Engine {
773    fn begin_row_lock_statement(
774        &self,
775    ) -> Box<dyn uqa_execution::statement::batch::context::RowLockStatementGuard + '_> {
776        Box::new(Engine::begin_row_lock_statement(self))
777    }
778    fn statement_row_lock_cache(
779        &self,
780    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
781    {
782        Engine::statement_row_lock_cache(self)
783    }
784}
785
786impl Drop for RowLockStatementScope<'_> {
787    fn drop(&mut self) {
788        self.engine.session.row_lock_statements.lock().pop();
789    }
790}
791
792impl uqa_execution::row_locks::retry_cache::CommittedRowSource for crate::Engine {
793    fn get_committed_document(
794        &self,
795        table: &str,
796        doc_id: uqa_core::DocId,
797    ) -> Result<Option<uqa_storage::StoredDocument>, uqa_sql::SQLError> {
798        crate::Engine::get_committed_document(self, table, doc_id)
799    }
800}