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    BackendTransactionMode, Engine, SQLError, TransactionIntent, TransactionRowChange,
11    TransactionScope,
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        self.with_implicit_transaction_mutation(|engine| {
43            engine.ensure_row_mutation_allowed(table)?;
44            engine.prepare_explicit_transaction_writer()?;
45            f(engine)
46        })
47    }
48
49    /// 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.
50    pub(crate) fn with_implicit_row_write_transaction<R>(
51        &self,
52        table: &str,
53        doc_id: uqa_core::DocId,
54        strength: uqa_sql::ast::LockStrength,
55        f: impl FnOnce(&Self) -> Result<R, SQLError>,
56    ) -> Result<R, SQLError> {
57        self.row_write_transaction(table, Some((doc_id, strength)), true, f)
58    }
59
60    /// 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.
61    pub(crate) fn with_evaluating_row_write_transaction<R>(
62        &self,
63        table: &str,
64        doc_id: uqa_core::DocId,
65        strength: uqa_sql::ast::LockStrength,
66        f: impl FnOnce(&Self) -> Result<R, SQLError>,
67    ) -> Result<R, SQLError> {
68        self.with_implicit_row_write_transaction(table, doc_id, strength, |engine| {
69            let _statement_thread = engine.statement_thread_context().enter();
70            f(engine)
71        })
72    }
73
74    /// Run the write of an inserted row. One that may replace a row locks it as any typed row mutation does.
75    ///
76    /// 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.
77    pub(crate) fn with_inserted_row_write_transaction<R>(
78        &self,
79        table: &str,
80        doc_id: uqa_core::DocId,
81        inserted: uqa_execution::mutation::publication::InsertedIdentity,
82        f: impl FnOnce(&Self) -> Result<R, SQLError>,
83    ) -> Result<R, SQLError> {
84        if inserted.is_vacant() && self.versioned_backend_transactions() {
85            return self.row_write_transaction(table, None, !inserted.is_unused(), f);
86        }
87        self.with_implicit_row_write_transaction(
88            table,
89            doc_id,
90            uqa_sql::ast::LockStrength::ForUpdate,
91            f,
92        )
93    }
94
95    /// `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.
96    fn row_write_transaction<R>(
97        &self,
98        table: &str,
99        row: Option<(uqa_core::DocId, uqa_sql::ast::LockStrength)>,
100        refresh: bool,
101        f: impl FnOnce(&Self) -> Result<R, SQLError>,
102    ) -> Result<R, SQLError> {
103        let _statement = self.lock_statement_gate();
104        if self.storage.backend.is_none() && self.transaction_depth() == 0 {
105            self.ensure_row_mutation_allowed(table)?;
106            return f(self);
107        }
108        let operation = || {
109            self.ensure_row_mutation_allowed(table)?;
110            self.prepare_serializable_transaction_snapshot()?;
111            self.lock_relation(table, crate::row_locks::RelationLockMode::RowExclusive)?;
112            if let Some((doc_id, strength)) = row {
113                match self.lock_row(
114                    table,
115                    doc_id,
116                    strength,
117                    uqa_sql::ast::LockWait::Block,
118                    table,
119                )? {
120                    crate::row_locks::LockAcquire::Granted { .. } => {}
121                    crate::row_locks::LockAcquire::Skipped => {
122                        return Err(SQLError::Internal(
123                            "blocking typed row mutation unexpectedly skipped a row".into(),
124                        ));
125                    }
126                }
127            }
128            if refresh {
129                self.prepare_explicit_transaction_writer()?;
130            } else {
131                self.prepare_unrefreshed_transaction_writer()?;
132            }
133            f(self)
134        };
135        if self.transaction_depth() != 0 {
136            return self.run_existing_transaction_operation(operation, std::convert::identity);
137        }
138        let scope = TransactionScope::begin_implicit_statement(self, false)?;
139        self.run_transaction_scope(scope, |_| operation(), std::convert::identity)
140    }
141
142    fn row_lock_table_name(&self, table: &str) -> Result<String, SQLError> {
143        self.try_resolve_table_name(table)
144            .map_err(|error| {
145                SQLError::Internal(format!("resolve row-lock table `{table}`: {error}"))
146            })
147            .map(|resolved| resolved.unwrap_or_else(|| table.to_string()))
148    }
149
150    pub(crate) fn row_lock_change_requires_recheck(&self) -> Result<bool, SQLError> {
151        let Some(backend) = self.storage.backend.as_ref() else {
152            return Ok(true);
153        };
154        if self.storage.provider.is_none() {
155            return Ok(false);
156        }
157        if backend.transaction_model().is_versioned() {
158            return Ok(true);
159        }
160        let stack = self.session.transactions.lock();
161        let deferred_reader = stack.first().is_some_and(|frame| {
162            frame.intent == TransactionIntent::ReadOnly
163                || frame.backend_mode == BackendTransactionMode::Deferred
164        });
165        drop(stack);
166        if !deferred_reader {
167            return Ok(false);
168        }
169        backend
170            .transaction_has_written()
171            .map(|written| !written)
172            .map_err(|error| Self::storage_tx_error("inspect row-lock recheck snapshot", &error))
173    }
174
175    pub(crate) fn lock_row(
176        &self,
177        table: &str,
178        doc_id: uqa_core::DocId,
179        strength: uqa_sql::ast::LockStrength,
180        wait: uqa_sql::ast::LockWait,
181        display_name: &str,
182    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
183        let canonical = self.row_lock_table_name(table)?;
184        let key = crate::row_locks::RowLockKey {
185            table: self.row_locks.table_key(&canonical),
186            doc_id,
187        };
188        self.row_locks.acquire(&crate::row_locks::LockRequest {
189            session_id: self.session_id,
190            key,
191            strength,
192            mark: self.current_lock_mark(),
193            wait,
194            cancel: &self.runtime.cancellation,
195            relation: display_name,
196        })
197    }
198
199    /// 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.
200    pub(crate) fn lock_scoring_parameter_write(&self, name: &str) -> Result<(), SQLError> {
201        let Some(backend) = self
202            .storage
203            .backend
204            .as_ref()
205            .filter(|backend| backend.transaction_model().is_versioned())
206        else {
207            return Ok(());
208        };
209        if self.transaction_depth() == 0 {
210            return Err(SQLError::Internal(
211                "scoring parameter writes require an active transaction".into(),
212            ));
213        }
214        self.row_locks.acquire(&crate::row_locks::LockRequest {
215            session_id: self.session_id,
216            key: crate::row_locks::RowLockKey {
217                table: self.row_locks.scoring_parameters_key(name),
218                doc_id: 0,
219            },
220            strength: uqa_sql::ast::LockStrength::ForUpdate,
221            mark: self.current_lock_mark(),
222            wait: uqa_sql::ast::LockWait::Block,
223            cancel: &self.runtime.cancellation,
224            relation: name,
225        })?;
226        backend
227            .refresh_transaction_snapshot(&self.runtime.cancellation)
228            .map_err(|error| Self::storage_tx_error("refresh scoring parameters", &error))
229    }
230
231    pub(crate) fn reserve_document_id_candidate(
232        &self,
233        table: &str,
234        doc_id: uqa_core::DocId,
235    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
236        let canonical = self.row_lock_table_name(table)?;
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.document_identity_key(&canonical),
241                doc_id,
242            },
243            strength: uqa_sql::ast::LockStrength::ForUpdate,
244            mark: self.current_lock_mark(),
245            wait: uqa_sql::ast::LockWait::SkipLocked,
246            cancel: &self.runtime.cancellation,
247            relation: table,
248        })
249    }
250
251    pub(crate) fn lock_key_reservation(
252        &self,
253        digest: [u8; 32],
254        display_name: &str,
255    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
256        let retained = self.row_locks.retain_key_reservation(digest);
257        let key = crate::row_locks::RowLockKey {
258            table: retained.table_key(),
259            doc_id: 0,
260        };
261        self.row_locks.acquire(&crate::row_locks::LockRequest {
262            session_id: self.session_id,
263            key,
264            strength: uqa_sql::ast::LockStrength::ForUpdate,
265            mark: self.current_lock_mark(),
266            wait: uqa_sql::ast::LockWait::Block,
267            cancel: &self.runtime.cancellation,
268            relation: display_name,
269        })
270    }
271
272    pub(crate) fn lock_key_reservations(
273        &self,
274        keys: &[[u8; 32]],
275        display_name: &str,
276    ) -> Result<Vec<crate::row_locks::LockAcquire>, SQLError> {
277        let mark = self.current_lock_mark();
278        let retained = keys
279            .iter()
280            .map(|key| self.row_locks.retain_key_reservation(*key))
281            .collect::<Vec<_>>();
282        let requests = retained
283            .iter()
284            .map(|identity| crate::row_locks::LockRequest {
285                session_id: self.session_id,
286                key: crate::row_locks::RowLockKey {
287                    table: identity.table_key(),
288                    doc_id: 0,
289                },
290                strength: uqa_sql::ast::LockStrength::ForUpdate,
291                mark,
292                wait: uqa_sql::ast::LockWait::Block,
293                cancel: &self.runtime.cancellation,
294                relation: display_name,
295            })
296            .collect::<Vec<_>>();
297        self.row_locks.acquire_batch(&requests)
298    }
299
300    pub(crate) fn lock_relation(
301        &self,
302        table: &str,
303        mode: crate::row_locks::RelationLockMode,
304    ) -> Result<(), SQLError> {
305        let canonical = self.row_lock_table_name(table)?;
306        self.row_locks.acquire_relation(
307            self.session_id,
308            self.row_locks.table_key(&canonical),
309            mode,
310            self.current_lock_mark(),
311            &self.runtime.cancellation,
312        )
313    }
314
315    pub(crate) fn temporary_relation_lock(
316        &self,
317        table: &str,
318        mode: crate::row_locks::RelationLockMode,
319    ) -> Result<crate::row_locks::ScopedRelationLock<'_>, SQLError> {
320        let canonical = self.row_lock_table_name(table)?;
321        self.prepare_transaction_lock_wait()?;
322        self.row_locks.acquire_scoped_relation(
323            self.session_id,
324            self.row_locks.table_key(&canonical),
325            mode,
326            self.temporary_relation_lock_marks()?,
327            &self.runtime.cancellation,
328        )
329    }
330
331    /// 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.
332    pub(crate) fn row_changed_in_open_transaction(
333        &self,
334        table: &str,
335        doc_id: uqa_core::DocId,
336    ) -> Result<bool, SQLError> {
337        let canonical = self.row_lock_table_name(table)?;
338        let key = crate::row_locks::RowLockKey {
339            table: self.row_locks.table_key(&canonical),
340            doc_id,
341        };
342        Ok(self.session.transactions.lock().iter().any(|frame| {
343            frame.row_changes.iter().any(|change| {
344                change.pending.key == key
345                    || matches!(
346                        change.pending.kind,
347                        crate::row_locks::PendingRowChangeKind::Rewrite(successor)
348                            if successor == key
349                    )
350            })
351        }))
352    }
353
354    /// 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.
355    pub(crate) fn committed_row_successor(
356        &self,
357        table: &str,
358        doc_id: uqa_core::DocId,
359    ) -> Result<crate::row_locks::RowChangeTarget, SQLError> {
360        let canonical = self.row_lock_table_name(table)?;
361        self.row_locks.row_successor_after(
362            &canonical,
363            doc_id,
364            &self.row_lock_snapshot_change_baseline()?,
365        )
366    }
367
368    pub(crate) fn committed_physical_row_successor(
369        &self,
370        table: &str,
371        doc_id: uqa_core::DocId,
372    ) -> Result<crate::row_locks::PhysicalRowChangeTarget, SQLError> {
373        let canonical = self.row_lock_table_name(table)?;
374        self.row_locks.physical_row_successor_after(
375            &canonical,
376            doc_id,
377            &self.row_lock_snapshot_change_baseline()?,
378        )
379    }
380
381    pub(crate) fn row_lock_table_for_hash(&self, table_hash: u64) -> Result<String, SQLError> {
382        let tables = self.storage.tables.read();
383        let mut matches = tables
384            .keys()
385            .map(uqa_storage::RelationIdentity::qualified_name)
386            .filter(|table| {
387                crate::row_locks::RowLockManager::stable_table_hash(table) == table_hash
388            });
389        let table = matches.next().ok_or_else(|| {
390            SQLError::Internal(format!(
391                "row-change successor refers to unknown relation hash {table_hash}"
392            ))
393        })?;
394        if matches.next().is_some() {
395            return Err(SQLError::Internal(format!(
396                "row-change successor relation hash {table_hash} is ambiguous"
397            )));
398        }
399        Ok(table)
400    }
401
402    fn deferred_foreign_key_checks_for_row(
403        &self,
404        table: &str,
405        row: crate::row_locks::RowLockKey,
406        rewrite: Option<(&crate::Document, &crate::Document)>,
407    ) -> Result<Vec<crate::DeferredForeignKeyCheck>, SQLError> {
408        let firing_relation =
409            crate::RelationIdentity::from_legacy_name(table).map_err(|error| {
410                SQLError::Internal(format!(
411                    "decode deferred foreign-key firing relation '{table}': {error}"
412                ))
413            })?;
414        let foreign_keys = self.foreign_keys_in_execution(table).map_err(|error| {
415            SQLError::Internal(format!(
416                "read deferred foreign keys for table `{table}`: {error}"
417            ))
418        })?;
419        let mut checks = Vec::new();
420        for foreign_key in foreign_keys {
421            if rewrite.is_some_and(|(old_document, new_document)| {
422                foreign_key.local_columns.iter().all(|column| {
423                    old_document
424                        .get(column)
425                        .cloned()
426                        .unwrap_or(crate::Value::Null)
427                        == new_document
428                            .get(column)
429                            .cloned()
430                            .unwrap_or(crate::Value::Null)
431                })
432            }) {
433                continue;
434            }
435            if foreign_key.enforced && self.foreign_key_is_deferred(table, &foreign_key)? {
436                checks.push(crate::DeferredForeignKeyCheck {
437                    constraint: self.foreign_key_constraint_identity(table, &foreign_key)?,
438                    firing_relation: firing_relation.clone(),
439                    row: Some(row),
440                    referenced_values: None,
441                });
442            }
443        }
444        Ok(checks)
445    }
446
447    fn note_row_change(
448        &self,
449        table: &str,
450        doc_id: uqa_core::DocId,
451        kind: crate::row_locks::PendingRowChangeKind,
452    ) -> Result<(), SQLError> {
453        let canonical = self.row_lock_table_name(table)?;
454        let key = crate::row_locks::RowLockKey {
455            table: self.row_locks.table_key(&canonical),
456            doc_id,
457        };
458        let source_generation = self.require_table(&canonical)?.storage_generation();
459        let mut stack = self.session.transactions.lock();
460        let pending = crate::row_locks::PendingRowChange { key, kind };
461        if let Some(frame) = stack.last_mut() {
462            let change = TransactionRowChange {
463                pending,
464                source_generation,
465                successor_generation: None,
466                query_origin: self
467                    .session_execution_view()
468                    .transaction_snapshot_identity(),
469            };
470            frame.row_changes.push(change);
471            self.follow_row_change(&mut stack, &change)
472        } else {
473            drop(stack);
474            let publication = self
475                .row_locks
476                .begin_change_publication(&self.runtime.cancellation)?;
477            let result = self
478                .row_locks
479                .publish_row_changes(self.session_id, [pending]);
480            drop(publication);
481            result
482        }
483    }
484
485    pub(crate) fn note_row_inserted(
486        &self,
487        table: &str,
488        doc_id: uqa_core::DocId,
489    ) -> Result<(), SQLError> {
490        self.note_row_change(
491            table,
492            doc_id,
493            crate::row_locks::PendingRowChangeKind::Insert,
494        )
495    }
496
497    pub(crate) fn note_row_changed(
498        &self,
499        table: &str,
500        doc_id: uqa_core::DocId,
501    ) -> Result<(), SQLError> {
502        self.note_row_change(
503            table,
504            doc_id,
505            crate::row_locks::PendingRowChangeKind::Update,
506        )
507    }
508
509    pub(crate) fn note_row_deleted(
510        &self,
511        table: &str,
512        doc_id: uqa_core::DocId,
513    ) -> Result<(), SQLError> {
514        self.note_row_change(
515            table,
516            doc_id,
517            crate::row_locks::PendingRowChangeKind::Delete,
518        )
519    }
520
521    pub(crate) fn defer_inserted_foreign_key_checks(
522        &self,
523        table: &str,
524        doc_id: uqa_core::DocId,
525    ) -> Result<(), SQLError> {
526        if self.session.transactions.lock().is_empty() {
527            return Ok(());
528        }
529        let canonical = self.row_lock_table_name(table)?;
530        let row = crate::row_locks::RowLockKey {
531            table: self.row_locks.table_key(&canonical),
532            doc_id,
533        };
534        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, None)?;
535        if let Some(frame) = self.session.transactions.lock().last_mut() {
536            frame.deferred_foreign_key_checks.extend(checks);
537        }
538        Ok(())
539    }
540
541    pub(crate) fn defer_rewritten_foreign_key_checks(
542        &self,
543        table: &str,
544        doc_id: uqa_core::DocId,
545        old_document: Option<&crate::Document>,
546        new_document: &crate::Document,
547    ) -> Result<(), SQLError> {
548        if self.session.transactions.lock().is_empty() {
549            return Ok(());
550        }
551        let canonical = self.row_lock_table_name(table)?;
552        let row = crate::row_locks::RowLockKey {
553            table: self.row_locks.table_key(&canonical),
554            doc_id,
555        };
556        let rewrite = old_document.map(|old_document| (old_document, new_document));
557        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, rewrite)?;
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    /// Defer the check of a referencing row that a change to a referenced row fired, under the constraint whose deferral governs it.
565    pub(crate) fn defer_foreign_key_check(
566        &self,
567        event: super::DeferredReferencedKey<'_>,
568        row_table: &str,
569        doc_id: uqa_core::DocId,
570        values: std::sync::Arc<[crate::Value]>,
571    ) -> Result<(), SQLError> {
572        let canonical_row_table = self.row_lock_table_name(row_table)?;
573        let check = crate::DeferredForeignKeyCheck {
574            constraint: self.referenced_key_constraint_identity(&event)?,
575            firing_relation: self.deferred_firing_relation(event.firing_table)?,
576            row: Some(crate::row_locks::RowLockKey {
577                table: self.row_locks.table_key(&canonical_row_table),
578                doc_id,
579            }),
580            referenced_values: Some(values),
581        };
582        let mut stack = self.session.transactions.lock();
583        let frame = stack.last_mut().ok_or_else(|| {
584            SQLError::Internal("deferred foreign-key check outside a transaction".into())
585        })?;
586        frame.deferred_foreign_key_checks.push(check);
587        Ok(())
588    }
589
590    fn deferred_firing_relation(
591        &self,
592        firing_table: &str,
593    ) -> Result<crate::RelationIdentity, SQLError> {
594        let canonical_firing_table = self.row_lock_table_name(firing_table)?;
595        crate::RelationIdentity::from_legacy_name(&canonical_firing_table).map_err(|error| {
596            SQLError::Internal(format!(
597                "decode deferred foreign-key firing relation '{canonical_firing_table}': {error}"
598            ))
599        })
600    }
601
602    pub(crate) fn defer_foreign_key_parent_event(
603        &self,
604        event: super::DeferredReferencedKey<'_>,
605    ) -> Result<(), SQLError> {
606        let check = crate::DeferredForeignKeyCheck {
607            constraint: self.referenced_key_constraint_identity(&event)?,
608            firing_relation: self.deferred_firing_relation(event.firing_table)?,
609            row: None,
610            referenced_values: None,
611        };
612        let mut stack = self.session.transactions.lock();
613        let frame = stack.last_mut().ok_or_else(|| {
614            SQLError::Internal("deferred foreign-key event outside a transaction".into())
615        })?;
616        frame.deferred_foreign_key_checks.push(check);
617        Ok(())
618    }
619
620    pub(crate) fn note_row_rewritten_between_tables(
621        &self,
622        old_table: &str,
623        old_doc_id: uqa_core::DocId,
624        new_table: &str,
625        new_doc_id: uqa_core::DocId,
626    ) -> Result<(), SQLError> {
627        let old_table = self.row_lock_table_name(old_table)?;
628        let new_table = self.row_lock_table_name(new_table)?;
629        let old = crate::row_locks::RowLockKey {
630            table: self.row_locks.table_key(&old_table),
631            doc_id: old_doc_id,
632        };
633        let new = crate::row_locks::RowLockKey {
634            table: self.row_locks.table_key(&new_table),
635            doc_id: new_doc_id,
636        };
637        let source_generation = self.require_table(&old_table)?.storage_generation();
638        let successor_generation = self.require_table(&new_table)?.storage_generation();
639        let mut stack = self.session.transactions.lock();
640        let pending = crate::row_locks::PendingRowChange {
641            key: old,
642            kind: crate::row_locks::PendingRowChangeKind::Rewrite(new),
643        };
644        if let Some(frame) = stack.last_mut() {
645            for check in &mut frame.deferred_foreign_key_checks {
646                if check.row == Some(old) {
647                    check.row = Some(new);
648                }
649            }
650            let change = TransactionRowChange {
651                pending,
652                source_generation,
653                successor_generation: Some(successor_generation),
654                query_origin: self
655                    .session_execution_view()
656                    .transaction_snapshot_identity(),
657            };
658            frame.row_changes.push(change);
659            self.follow_row_change(&mut stack, &change)
660        } else {
661            drop(stack);
662            let publication = self
663                .row_locks
664                .begin_change_publication(&self.runtime.cancellation)?;
665            let result = self
666                .row_locks
667                .publish_row_changes(self.session_id, [pending]);
668            drop(publication);
669            result
670        }
671    }
672
673    pub(crate) fn row_lock_manager(&self) -> std::sync::Arc<crate::row_locks::RowLockManager> {
674        std::sync::Arc::clone(&self.row_locks)
675    }
676
677    /// 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.
678    pub(crate) fn begin_row_lock_statement(&self) -> RowLockStatementScope<'_> {
679        self.session.row_lock_statements.lock().push(None);
680        RowLockStatementScope { engine: self }
681    }
682
683    /// 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.
684    pub(crate) fn statement_row_lock_cache(
685        &self,
686    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
687    {
688        let budget_bytes = self.work_mem_bytes()?;
689        let baseline = self.row_lock_snapshot_change_baseline()?;
690        let mut statements = self.session.row_lock_statements.lock();
691        let Some(slot) = statements.last_mut() else {
692            drop(statements);
693            return Ok(std::sync::Arc::new(
694                uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
695                    budget_bytes,
696                    self.row_lock_manager(),
697                    baseline,
698                ),
699            ));
700        };
701        if let Some(cache) = slot.as_ref() {
702            return Ok(std::sync::Arc::clone(cache));
703        }
704        let cache = std::sync::Arc::new(
705            uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
706                budget_bytes,
707                self.row_lock_manager(),
708                baseline,
709            ),
710        );
711        *slot = Some(std::sync::Arc::clone(&cache));
712        Ok(cache)
713    }
714
715    pub(crate) fn row_lock_snapshot_change_baseline(
716        &self,
717    ) -> Result<crate::row_locks::RowChangeBaseline, SQLError> {
718        if let Some(frame) = self.session.transactions.lock().first() {
719            return Ok(frame.snapshot_change_baseline.clone());
720        }
721        self.row_locks
722            .begin_change_snapshot(&self.runtime.cancellation)?
723            .baseline()
724    }
725
726    pub(crate) fn update_statement_row_lock_baseline(
727        &self,
728        baseline: crate::row_locks::RowChangeBaseline,
729    ) {
730        if let Some(Some(cache)) = self.session.row_lock_statements.lock().last() {
731            cache.set_snapshot_baseline(baseline);
732        }
733    }
734
735    pub(crate) fn rollback_row_lock_acquisition(
736        &self,
737        acquisition: crate::row_locks::RowLockAcquisition,
738    ) {
739        self.row_locks.rollback_acquisition(acquisition);
740    }
741}
742
743/// 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.
744pub(crate) struct RowLockStatementScope<'engine> {
745    engine: &'engine Engine,
746}
747
748impl uqa_execution::statement::batch::context::RowLockStatementGuard for RowLockStatementScope<'_> {}
749
750impl uqa_execution::statement::batch::context::BatchRowLocks for Engine {
751    fn begin_row_lock_statement(
752        &self,
753    ) -> Box<dyn uqa_execution::statement::batch::context::RowLockStatementGuard + '_> {
754        Box::new(Engine::begin_row_lock_statement(self))
755    }
756    fn statement_row_lock_cache(
757        &self,
758    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
759    {
760        Engine::statement_row_lock_cache(self)
761    }
762}
763
764impl Drop for RowLockStatementScope<'_> {
765    fn drop(&mut self) {
766        self.engine.session.row_lock_statements.lock().pop();
767    }
768}
769
770impl uqa_execution::row_locks::retry_cache::CommittedRowSource for crate::Engine {
771    fn get_committed_document(
772        &self,
773        table: &str,
774        doc_id: uqa_core::DocId,
775    ) -> Result<Option<uqa_storage::StoredDocument>, uqa_sql::SQLError> {
776        crate::Engine::get_committed_document(self, table, doc_id)
777    }
778}