Skip to main content

uqa_execution/query/
locking.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Row-lock target resolution and the physical `LockRows` operator.
8
9use super::recheck_source::{LockRowsRecheckInput, LockRowsRecheckSource};
10use crate::query::{binding::bind_source_plan_schema, CteScope};
11use crate::row_locks::{
12    recheck::recheck_storage_names_match, retry_cache::RowLockRetryCache, LockAcquire,
13};
14use crate::{Batch, ExecResult, PhysicalOperator, PhysicalRow, RowProjectionValue, RowSchema};
15use uqa_sql::ast::{LockStrength, LockWait, LockingClause, RelationPersistence};
16use uqa_sql::{
17    plan::{QueryBlockPlan, QueryPlan, RelationalPlan, SourcePlan},
18    SQLError, SQLParam, ScalarExpr,
19};
20pub mod context;
21pub use context::RowLockContext;
22
23pub use crate::query::scope::ResolvedRowLock;
24
25pub fn query_has_row_locks(query: &QueryPlan) -> bool {
26    query_plan_has_row_locks(query)
27}
28
29mod relations;
30mod targets;
31pub use relations::{lock_explained_relations, lock_query_relations};
32
33fn validate_cte_row_locks<S: Clone + Send + Sync + 'static>(
34    context: RowLockContext<'_, S>,
35    body: &uqa_sql::plan::CtePlanBody,
36    params: &[SQLParam],
37    ctes: &CteScope<S>,
38) -> Result<(), SQLError> {
39    match body {
40        uqa_sql::plan::CtePlanBody::Query(query) => {
41            validate_query_plan_row_locks(context, query, params, ctes)
42        }
43        uqa_sql::plan::CtePlanBody::Command(command) => {
44            for cte in command.ctes() {
45                validate_cte_row_locks(context, &cte.body, params, ctes)?;
46            }
47            for query in command.query_inputs() {
48                validate_query_plan_row_locks(context, query, params, ctes)?;
49            }
50            if let Some(source) = command.source_input() {
51                validate_source_row_locks(context, source, params, ctes)?;
52            }
53            Ok(())
54        }
55    }
56}
57
58/// Resolve cursor row-lock targets without opening or pulling the query. `PostgreSQL` performs these declaration-time checks even though expression evaluation and tuple locking wait until FETCH.
59pub fn validate_query_row_locks<S: Clone + Send + Sync + 'static>(
60    context: RowLockContext<'_, S>,
61    query: &QueryPlan,
62    params: &[SQLParam],
63) -> Result<(), SQLError> {
64    let ctes = context.scopes.current_routine_scope()?;
65    validate_query_plan_row_locks(context, query, params, &ctes)
66}
67
68fn validate_query_plan_row_locks<S: Clone + Send + Sync + 'static>(
69    context: RowLockContext<'_, S>,
70    query: &QueryPlan,
71    params: &[SQLParam],
72    ctes: &CteScope<S>,
73) -> Result<(), SQLError> {
74    for cte in &query.ctes {
75        validate_cte_row_locks(context, &cte.body, params, ctes)?;
76    }
77    match &query.root {
78        RelationalPlan::QueryBlock(block) => {
79            for subquery in &block.subqueries {
80                validate_query_plan_row_locks(context, subquery, params, ctes)?;
81            }
82            if let Some(from) = block.from.as_ref() {
83                validate_source_row_locks(context, from, params, ctes)?;
84                resolve_row_locks(
85                    context,
86                    from,
87                    &block.locking,
88                    block.r#where.as_ref(),
89                    params,
90                    ctes,
91                )?;
92            }
93        }
94        RelationalPlan::SetOp { left, right, .. } => {
95            validate_query_plan_row_locks(context, left, params, ctes)?;
96            validate_query_plan_row_locks(context, right, params, ctes)?;
97        }
98        RelationalPlan::Values { subqueries, .. } => {
99            for subquery in subqueries {
100                validate_query_plan_row_locks(context, subquery, params, ctes)?;
101            }
102        }
103    }
104    Ok(())
105}
106
107fn validate_source_row_locks<S: Clone + Send + Sync + 'static>(
108    context: RowLockContext<'_, S>,
109    source: &SourcePlan,
110    params: &[SQLParam],
111    ctes: &CteScope<S>,
112) -> Result<(), SQLError> {
113    match source {
114        SourcePlan::Join { left, right, .. } => {
115            validate_source_row_locks(context, left, params, ctes)?;
116            validate_source_row_locks(context, right, params, ctes)
117        }
118        SourcePlan::Subquery { body, .. } => {
119            validate_query_plan_row_locks(context, body, params, ctes)
120        }
121        SourcePlan::RetainedRows(_)
122        | SourcePlan::Table { .. }
123        | SourcePlan::Values { .. }
124        | SourcePlan::Function { .. }
125        | SourcePlan::FunctionGroup { .. } => Ok(()),
126    }
127}
128
129use uqa_sql::semantics::locking::query_plan_has_row_locks;
130
131mod resolution;
132pub use resolution::resolve_row_locks;
133
134fn locks_non_temporary_relation<S: Clone + Send + Sync + 'static>(
135    context: RowLockContext<'_, S>,
136    locks: &[ResolvedRowLock],
137) -> Result<bool, SQLError> {
138    for lock in locks {
139        let persistence = context
140            .catalog
141            .table_persistence(&lock.storage_name)
142            .map_err(|error| {
143                SQLError::Internal(format!(
144                    "resolve row-lock target `{}`: {error}",
145                    lock.storage_name
146                ))
147            })?;
148        if persistence != Some(RelationPersistence::Temporary) {
149            return Ok(true);
150        }
151    }
152    Ok(false)
153}
154
155fn source_contains_join_alias(source: &SourcePlan, target: &str) -> bool {
156    match source {
157        SourcePlan::Join {
158            left, right, alias, ..
159        } => {
160            alias.as_deref() == Some(target)
161                || source_contains_join_alias(left, target)
162                || source_contains_join_alias(right, target)
163        }
164        SourcePlan::RetainedRows(_)
165        | SourcePlan::Table { .. }
166        | SourcePlan::Values { .. }
167        | SourcePlan::Function { .. }
168        | SourcePlan::FunctionGroup { .. }
169        | SourcePlan::Subquery { .. } => false,
170    }
171}
172
173mod execution;
174mod null_rejection;
175
176fn merge_lock_wait(left: LockWait, right: LockWait) -> LockWait {
177    match (left, right) {
178        (LockWait::NoWait, _) | (_, LockWait::NoWait) => LockWait::NoWait,
179        (LockWait::SkipLocked, _) | (_, LockWait::SkipLocked) => LockWait::SkipLocked,
180        (LockWait::Block, LockWait::Block) => LockWait::Block,
181    }
182}
183
184pub use uqa_sql::semantics::locking::apply_propagated_view_lock;
185
186mod leaf_validation;
187use leaf_validation::{
188    collect_source_leaf_plans, collect_source_leaves, copy_recheck_source_row,
189    validate_locking_block_shape,
190};
191
192pub struct LockRows<'a, S: Clone> {
193    input: Box<dyn PhysicalOperator + 'a>,
194    context: RowLockContext<'a, S>,
195    params: &'a [SQLParam],
196    targets: uqa_core::memory::Produced<Vec<ResolvedRowLock>>,
197    max_rows: Option<u64>,
198    emitted: u64,
199    pending_rows: std::vec::IntoIter<PhysicalRow>,
200    discard_lock_origins: bool,
201    retry_cache: Option<std::sync::Arc<RowLockRetryCache>>,
202    recheck_source: Option<LockRowsRecheckSource<S>>,
203    schema: RowSchema,
204    /// Base relations that already hold this statement's `RowShare` lock. A view or derived-table target reveals its base relations only through row origins, so the relation lock is taken on first sight of each.
205    relation_locked: std::collections::BTreeSet<crate::RowLockName>,
206}
207
208impl<'a, S: Clone> LockRows<'a, S> {
209    #[expect(
210        clippy::too_many_arguments,
211        reason = "keeps execution context inputs aligned"
212    )]
213    pub fn new(
214        input: Box<dyn PhysicalOperator + 'a>,
215        context: RowLockContext<'a, S>,
216        params: &'a [SQLParam],
217        targets: uqa_core::memory::Produced<Vec<ResolvedRowLock>>,
218        max_rows: Option<u64>,
219        discard_lock_origins: bool,
220        retry_cache: Option<std::sync::Arc<RowLockRetryCache>>,
221        recheck_source: Option<LockRowsRecheckSource<S>>,
222    ) -> Self {
223        let schema = input.row_schema().clone();
224        Self {
225            input,
226            context,
227            params,
228            targets,
229            max_rows,
230            emitted: 0,
231            pending_rows: Vec::new().into_iter(),
232            discard_lock_origins,
233            retry_cache,
234            recheck_source,
235            schema,
236            relation_locked: std::collections::BTreeSet::new(),
237        }
238    }
239}
240
241impl<S: Clone + Send + Sync + 'static> PhysicalOperator for LockRows<'_, S> {
242    fn row_schema(&self) -> &RowSchema {
243        &self.schema
244    }
245
246    fn estimated_cardinality(&self) -> Option<u64> {
247        match (self.input.estimated_cardinality(), self.max_rows) {
248            (Some(input), Some(max_rows)) => Some(input.min(max_rows)),
249            (estimate, None) | (None, estimate) => estimate,
250        }
251    }
252
253    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
254        self.input.output_ordering()
255    }
256
257    fn open(&mut self) -> ExecResult<()> {
258        self.emitted = 0;
259        self.pending_rows = Vec::new().into_iter();
260        self.input.open()
261    }
262
263    // Keep the virtual pull boundary intact under `ThinLTO`; the acquisition and recheck state machines below are deliberately separate optimized functions.
264    #[inline(never)]
265    fn next(&mut self) -> ExecResult<Option<Batch>> {
266        if self
267            .max_rows
268            .is_some_and(|max_rows| self.emitted >= max_rows)
269        {
270            return Ok(None);
271        }
272        loop {
273            self.context.cancellation.check().map_err(SQLError::from)?;
274            if let Some(row) = self.pending_rows.next() {
275                if let Some(mut row) = self.lock_physical_row(row)? {
276                    if self.discard_lock_origins {
277                        row.discard_lock_origins_mut();
278                    }
279                    self.emitted = self.emitted.saturating_add(1);
280                    // One row per batch keeps locking demand-driven: an enclosing consumer such as an outer LIMIT over a locking derived table stops pulling after the rows it needs, so rows it never consumes are never locked (PostgreSQL 18 LockRows semantics). Batching ahead would lock rows the consumer discards.
281                    return Ok(Some(Batch::from_physical_rows(
282                        self.schema.clone(),
283                        vec![row],
284                    )));
285                }
286                continue;
287            }
288            let Some(batch) = self.input.next_with_demand(crate::physical::demand::ONE)? else {
289                return Ok(None);
290            };
291            self.pending_rows = batch.rows.into_iter();
292        }
293    }
294
295    fn close(&mut self) -> ExecResult<()> {
296        self.input.close()
297    }
298}
299
300pub fn attach_lock_rows<'a, S: Clone + Send + Sync + 'static>(
301    context: RowLockContext<'a, S>,
302    operator: Box<dyn PhysicalOperator + 'a>,
303    statement: &QueryBlockPlan,
304    params: &'a [SQLParam],
305    ctes: &CteScope<S>,
306    max_rows: Option<u64>,
307    recheck_source: Option<LockRowsRecheckInput<'_, S>>,
308) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError> {
309    crate::physical::construction::OperatorBuild::build(operator, |operator| {
310        let Some(first_clause) = statement.locking.first() else {
311            return Ok(());
312        };
313        if ctes.row_lock_recheck_active() {
314            // A tuple-local recheck re-executes the plan below its own LockRows boundary. Locks for the candidate are already held, so nested locking is suppressed while lock identities keep flowing.
315            return Ok(());
316        }
317        validate_locking_block_shape(statement, first_clause.strength)?;
318        let Some(from) = statement.from.as_ref() else {
319            return Ok(());
320        };
321        let targets = resolve_row_locks(
322            context,
323            from,
324            &statement.locking,
325            statement.r#where.as_ref(),
326            params,
327            ctes,
328        )?;
329        if targets.is_empty() {
330            return Ok(());
331        }
332        let mut locked_relations = std::collections::BTreeSet::new();
333        for target in targets.iter().filter(|target| !target.identity_source) {
334            if locked_relations.insert(target.storage_name.clone()) {
335                context.session.lock_relation(
336                    &target.storage_name,
337                    crate::row_locks::RelationLockMode::RowShare,
338                )?;
339            }
340        }
341        // The recheck context is shared per SQL statement through the context session, so every locking scope reaches it: top-level queries, DML sources, DML CTEs, CREATE TABLE AS, prepared execution, and EXPLAIN ANALYZE bodies.
342        let retry_cache = context.session.statement_row_lock_cache()?;
343        let recheck_source = recheck_source
344            .map(LockRowsRecheckInput::retain)
345            .transpose()?;
346        operator.wrap(|input| {
347            Box::new(LockRows::new(
348                input,
349                context,
350                params,
351                targets,
352                max_rows,
353                !ctes.lock_identities.retain_after_lock,
354                Some(retry_cache),
355                recheck_source,
356            ))
357        });
358        Ok(())
359    })
360}
361
362fn validate_lock_relation_aliases(
363    from: &SourcePlan,
364    locking: &[LockingClause],
365) -> Result<(), SQLError> {
366    for clause in locking {
367        if clause
368            .relations
369            .iter()
370            .any(|relation| source_contains_join_alias(from, relation))
371        {
372            return Err(SQLError::Unsupported(format!(
373                "{} cannot be applied to a join",
374                clause.strength.sql_name()
375            )));
376        }
377    }
378    Ok(())
379}