Skip to main content

uqa_execution/mutation/
triggers.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `BEFORE`/`AFTER`, row-level, and statement-level trigger execution.
8
9use std::cell::RefCell;
10use std::collections::{BTreeMap, BTreeSet};
11
12use uqa_core::{DocId, Value};
13use uqa_sql::ast::{TriggerEvent, TriggerTiming};
14use uqa_sql::error::Result;
15use uqa_sql::plpgsql::{bind_expr, ResolvedVariable, VariableResolver};
16use uqa_sql::SQLError;
17use uqa_storage::document_store::Document;
18
19use context::TriggerContext;
20
21#[cfg(test)]
22mod tests;
23use uqa_core::RelationIdentity;
24pub mod context;
25
26use crate::routines::TriggerRoutineContext;
27
28type TransitionCaptureKey = (String, &'static str, Vec<String>);
29type TransitionCaptureStack = Vec<BTreeMap<TransitionCaptureKey, bool>>;
30
31thread_local! {
32    static ACTIVE_TRANSITION_RELATIONS: RefCell<Vec<BTreeMap<String, crate::SharedSpill>>> = const { RefCell::new(Vec::new()) };
33    static TRANSITION_CAPTURE_CACHE: RefCell<TransitionCaptureStack> = const { RefCell::new(Vec::new()) };
34    /// How many trigger functions this thread is inside.
35    static TRIGGER_DEPTH: std::cell::Cell<i64> = const { std::cell::Cell::new(0) };
36}
37
38/// How many trigger functions the running code is inside, as `pg_trigger_depth()` reports it: 0 outside any trigger.
39pub fn trigger_depth() -> i64 {
40    TRIGGER_DEPTH.with(std::cell::Cell::get)
41}
42
43/// One trigger function running until the guard drops.
44struct TriggerDepthScope;
45
46impl TriggerDepthScope {
47    fn enter() -> Self {
48        TRIGGER_DEPTH.with(|depth| depth.set(depth.get() + 1));
49        Self
50    }
51}
52
53impl Drop for TriggerDepthScope {
54    fn drop(&mut self) {
55        TRIGGER_DEPTH.with(|depth| depth.set(depth.get() - 1));
56    }
57}
58
59pub struct TransitionRelationScope;
60
61impl TransitionRelationScope {
62    fn enter(relations: BTreeMap<String, crate::SharedSpill>) -> Self {
63        ACTIVE_TRANSITION_RELATIONS.with(|active| active.borrow_mut().push(relations));
64        Self
65    }
66
67    fn empty() -> Self {
68        Self::enter(BTreeMap::new())
69    }
70}
71
72impl Drop for TransitionRelationScope {
73    fn drop(&mut self) {
74        ACTIVE_TRANSITION_RELATIONS.with(|relations| {
75            let removed = relations.borrow_mut().pop();
76            debug_assert!(
77                removed.is_some(),
78                "transition relation scope stack underflow"
79            );
80        });
81    }
82}
83
84pub fn current_transition_relations() -> BTreeMap<String, crate::SharedSpill> {
85    ACTIVE_TRANSITION_RELATIONS
86        .with(|relations| relations.borrow().last().cloned().unwrap_or_default())
87}
88
89pub fn current_transition_relation_names() -> BTreeSet<String> {
90    ACTIVE_TRANSITION_RELATIONS.with(|relations| {
91        relations
92            .borrow()
93            .last()
94            .map(|relations| relations.keys().cloned().collect())
95            .unwrap_or_default()
96    })
97}
98
99pub fn enter_empty_transition_relation_scope() -> TransitionRelationScope {
100    TransitionRelationScope::empty()
101}
102
103/// A statement that writes rows. What it resolves about the triggers of its tables, which row triggers they have and whether their transitions are captured, holds until it ends.
104pub struct TriggerStatementScope;
105
106impl TriggerStatementScope {
107    pub fn enter() -> Self {
108        TRANSITION_CAPTURE_CACHE.with(|cache| cache.borrow_mut().push(BTreeMap::new()));
109        row_triggers::enter();
110        Self
111    }
112}
113
114impl Drop for TriggerStatementScope {
115    fn drop(&mut self) {
116        row_triggers::leave();
117        TRANSITION_CAPTURE_CACHE.with(|cache| {
118            let removed = cache.borrow_mut().pop();
119            debug_assert!(
120                removed.is_some(),
121                "transition capture cache stack underflow"
122            );
123        });
124    }
125}
126
127pub mod events;
128pub mod queue;
129mod transitions;
130pub use transitions::{transition_capture_required, TransitionTables};
131
132mod row_triggers;
133mod rows;
134use rows::{
135    trigger_column_metadata, trigger_document, trigger_record, TriggerColumnMetadata,
136    TriggerVariableResolver,
137};
138
139fn operation_name(event: TriggerEvent) -> &'static str {
140    match event {
141        TriggerEvent::Insert => "INSERT",
142        TriggerEvent::Update => "UPDATE",
143        TriggerEvent::Delete => "DELETE",
144        TriggerEvent::Truncate => "TRUNCATE",
145    }
146}
147
148fn timing_name(timing: TriggerTiming) -> &'static str {
149    match timing {
150        TriggerTiming::Before => "BEFORE",
151        TriggerTiming::After => "AFTER",
152        TriggerTiming::InsteadOf => "INSTEAD OF",
153    }
154}
155
156fn trigger_condition_matches(
157    context: &TriggerContext<'_>,
158    condition: Option<&uqa_sql::ast::Expr>,
159    old: &Value,
160    new: &Value,
161    columns: &BTreeMap<String, TriggerColumnMetadata>,
162) -> Result<bool> {
163    let Some(condition) = condition else {
164        return Ok(true);
165    };
166    let condition = bind_expr(
167        condition,
168        &mut TriggerVariableResolver { old, new, columns },
169    )?;
170    Ok(uqa_sql::expr::truthy(
171        &context.expressions.evaluate(&condition)?,
172    ))
173}
174
175struct TriggerInvocation<'a> {
176    table: &'a str,
177    trigger: &'a uqa_sql::catalog::events::StoredTrigger,
178    timing: TriggerTiming,
179    event: TriggerEvent,
180    row: bool,
181    old: Value,
182    new: Value,
183}
184
185fn invoke_trigger(
186    context: &TriggerContext<'_>,
187    invocation: TriggerInvocation<'_>,
188    transition_tables: Option<&TransitionTables>,
189) -> Result<Value> {
190    let relation = RelationIdentity::from_legacy_name(invocation.table).map_err(|error| {
191        SQLError::Internal(format!(
192            "decode trigger relation `{}`: {error}",
193            invocation.table
194        ))
195    })?;
196    let function = context.routines.resolve_bound_trigger_function(
197        &invocation.trigger.definition.function,
198        invocation.trigger.function_object_id,
199    )?;
200    let _transition_scope = match transition_tables {
201        Some(tables) => tables.enter(&invocation.trigger.definition)?,
202        None if invocation
203            .trigger
204            .definition
205            .transition_relations
206            .is_empty() =>
207        {
208            TransitionRelationScope::empty()
209        }
210        None => {
211            return Err(SQLError::Internal(format!(
212                "trigger `{}` requested unavailable transition tables",
213                invocation.trigger.definition.name
214            )))
215        }
216    };
217    let _depth = TriggerDepthScope::enter();
218    context.routines.execute_trigger_routine(
219        &function,
220        &TriggerRoutineContext {
221            row_schema: uqa_sql::RowSchema::with_column_metadata(
222                None,
223                context
224                    .catalog
225                    .trigger_relation_definitions(invocation.table)?
226                    .into_iter()
227                    .map(|column| (column.name, Some(column.ty), column.collation_oid)),
228            ),
229            old: invocation.old,
230            new: invocation.new,
231            name: invocation.trigger.definition.name.clone(),
232            when: timing_name(invocation.timing).into(),
233            level: if invocation.row { "ROW" } else { "STATEMENT" }.into(),
234            operation: operation_name(invocation.event).into(),
235            relation_oid: crate::catalog::projection::event_relation_oid(
236                &context.projection,
237                invocation.table,
238            )?,
239            table_name: relation.name,
240            table_schema: relation.schema,
241            arguments: invocation.trigger.definition.arguments.clone(),
242        },
243    )
244}
245
246fn positional_trigger_record(
247    columns: &[(String, uqa_sql::ast::ColumnType)],
248    values: Option<&[Value]>,
249) -> Result<Value> {
250    if values.is_some_and(|values| values.len() != columns.len()) {
251        return Err(SQLError::Internal(
252            "INSTEAD OF trigger row does not match the view row type".into(),
253        ));
254    }
255    Ok(Value::Record(
256        columns
257            .iter()
258            .enumerate()
259            .map(|(position, (name, _))| {
260                (
261                    name.clone(),
262                    values
263                        .and_then(|values| values.get(position))
264                        .cloned()
265                        .unwrap_or(Value::Null),
266                )
267            })
268            .collect::<Vec<_>>()
269            .into(),
270    ))
271}
272
273fn normalize_instead_of_trigger_record(
274    columns: &[(String, uqa_sql::ast::ColumnType)],
275    value: Value,
276) -> Result<Option<Vec<Value>>> {
277    let fields = match value {
278        Value::Null => return Ok(None),
279        Value::Record(fields) => fields.into_iter().collect::<BTreeMap<_, _>>(),
280        _ => {
281            return Err(SQLError::Routine {
282                sqlstate: "39P01".into(),
283                message: "trigger function returned non-composite value".into(),
284            })
285        }
286    };
287    if let Some(unknown) = fields
288        .keys()
289        .find(|name| !columns.iter().any(|(column, _)| column == *name))
290    {
291        return Err(SQLError::UnknownColumn(unknown.clone()));
292    }
293    // The routine result has already passed descriptor validation; these values are admitted, not new input.
294    Ok(Some(
295        columns
296            .iter()
297            .map(|(name, _)| fields.get(name).cloned().unwrap_or(Value::Null))
298            .collect(),
299    ))
300}
301
302/// Run the `INSTEAD OF` row triggers of `view` for one row in name order, as `ExecIRInsertTriggers`, `ExecIRUpdateTriggers` and `ExecIRDeleteTriggers` do, and return the row the command then counts, checks and returns: the last trigger's result for INSERT and UPDATE and the original OLD row for DELETE, or `None` when a trigger returns NULL. When `session_replication_role` suppresses every trigger, the row is counted as it stands, although nothing performs the command.
303pub fn fire_instead_of_row_triggers(
304    context: &TriggerContext<'_>,
305    view: &str,
306    event: TriggerEvent,
307    old_values: Option<&[Value]>,
308    new_values: Option<&[Value]>,
309    updated_columns: &[String],
310) -> Result<Option<Vec<Value>>> {
311    let columns = context.catalog.rule_relation_columns(view)?;
312    let old = positional_trigger_record(&columns, old_values)?;
313    let mut new = positional_trigger_record(&columns, new_values)?;
314    let triggers = context.catalog.triggers_for(
315        view,
316        TriggerTiming::InsteadOf,
317        event,
318        true,
319        updated_columns,
320    )?;
321    if triggers.is_empty()
322        && !context
323            .catalog
324            .has_trigger_definition(view, TriggerTiming::InsteadOf, event, true)?
325    {
326        return Err(SQLError::Routine {
327            sqlstate: "55000".into(),
328            message: format!(
329                "cannot {} view \"{}\": no active INSTEAD OF trigger",
330                operation_name(event).to_ascii_lowercase(),
331                RelationIdentity::from_legacy_name(view)
332                    .map_or_else(|_| view.to_string(), |relation| relation.name)
333            ),
334        });
335    }
336    for trigger in triggers {
337        let returned = invoke_trigger(
338            context,
339            TriggerInvocation {
340                table: view,
341                trigger: &trigger,
342                timing: TriggerTiming::InsteadOf,
343                event,
344                row: true,
345                old: old.clone(),
346                new: new.clone(),
347            },
348            None,
349        )?;
350        let Some(values) = normalize_instead_of_trigger_record(&columns, returned)? else {
351            return Ok(None);
352        };
353        if event != TriggerEvent::Delete {
354            new = positional_trigger_record(&columns, Some(&values))?;
355        }
356    }
357    let final_record = if event == TriggerEvent::Delete {
358        old
359    } else {
360        new
361    };
362    normalize_instead_of_trigger_record(&columns, final_record)
363}
364
365pub fn fire_statement_triggers(
366    context: &TriggerContext<'_>,
367    table: &str,
368    timing: TriggerTiming,
369    event: TriggerEvent,
370    updated_columns: &[String],
371) -> Result<()> {
372    fire_statement_triggers_with_transition(context, table, timing, event, updated_columns, None)
373}
374
375fn fire_statement_triggers_with_transition(
376    context: &TriggerContext<'_>,
377    table: &str,
378    timing: TriggerTiming,
379    event: TriggerEvent,
380    updated_columns: &[String],
381    transition_tables: Option<&TransitionTables>,
382) -> Result<()> {
383    for trigger in context
384        .catalog
385        .triggers_for(table, timing, event, false, updated_columns)?
386    {
387        let _ = invoke_trigger(
388            context,
389            TriggerInvocation {
390                table,
391                trigger: &trigger,
392                timing,
393                event,
394                row: false,
395                old: Value::Null,
396                new: Value::Null,
397            },
398            transition_tables,
399        )?;
400    }
401    Ok(())
402}
403
404/// Whether `table` has BEFORE ROW triggers for `event`, whatever replication role fires them, which make `PostgreSQL` fetch a row through `GetTupleForTrigger` before it updates or deletes it.
405pub fn has_before_row_triggers(
406    context: &TriggerContext<'_>,
407    table: &str,
408    event: TriggerEvent,
409) -> Result<bool> {
410    Ok(!row_triggers::resolve(context, table, TriggerTiming::Before, event, None)?.is_empty())
411}
412
413pub fn fire_before_row_triggers(
414    context: &TriggerContext<'_>,
415    table: &str,
416    event: TriggerEvent,
417    doc_id: DocId,
418    old_document: Option<&Document>,
419    new_document: Option<&Document>,
420    updated_columns: &[String],
421) -> Result<Option<Document>> {
422    let triggers = row_triggers::resolve(
423        context,
424        table,
425        TriggerTiming::Before,
426        event,
427        Some(updated_columns),
428    )?;
429    let original = if event == TriggerEvent::Delete {
430        old_document
431    } else {
432        new_document
433    };
434    if !triggers
435        .iter()
436        .any(|trigger| row_triggers::fires(context, trigger))
437    {
438        return Ok(original.cloned());
439    }
440    let columns = trigger_column_metadata(context.catalog.trigger_relation_definitions(table)?);
441    let old = trigger_record(context, table, doc_id, old_document, false)?;
442    let mut new = trigger_record(context, table, doc_id, new_document, true)?;
443    let mut invoked = false;
444    for trigger in triggers.iter() {
445        // An earlier trigger of this row may have changed the role.
446        if !row_triggers::fires(context, trigger)
447            || !trigger_condition_matches(
448                context,
449                trigger.definition.when.as_ref(),
450                &old,
451                &new,
452                &columns,
453            )?
454        {
455            continue;
456        }
457        invoked = true;
458        let returned = invoke_trigger(
459            context,
460            TriggerInvocation {
461                table,
462                trigger,
463                timing: TriggerTiming::Before,
464                event,
465                row: true,
466                old: old.clone(),
467                new: new.clone(),
468            },
469            None,
470        )?;
471        if matches!(returned, Value::Null) {
472            return Ok(None);
473        }
474        if event != TriggerEvent::Delete {
475            new = returned;
476        }
477    }
478    if event == TriggerEvent::Delete || !invoked {
479        return Ok(original.cloned());
480    }
481    trigger_document(context, table, new)
482}
483
484/// Fire the AFTER ROW triggers of one queued row, and run its foreign key checks and referential actions, which are internal triggers that fire among the user triggers in the order of their names. A referential action queues the events of the rows it writes in `queue`. `transition_table` is the state whose transition tables collected the row, which the first trigger that reads them closes, after the internal triggers that precede it have run.
485fn fire_after_row_trigger(
486    context: &TriggerContext<'_>,
487    event: &AfterRowTriggerEvent,
488    transition_table: Option<usize>,
489    queue: &queue::AfterTriggerQueue,
490) -> Result<()> {
491    let mut checks = event.foreign_keys.iter().peekable();
492    for trigger in &event.triggers {
493        while let Some(check) =
494            checks.next_if(|check| check.precedes_trigger(&trigger.definition.name))
495        {
496            context.foreign_keys.run_foreign_key_check(check, queue)?;
497        }
498        if trigger.definition.constraint
499            && context.deferrals.constraint_trigger_is_deferred(trigger)?
500        {
501            context
502                .deferrals
503                .defer_constraint_trigger_event(DeferredConstraintTriggerEvent {
504                    constraint: trigger.constraint_identity()?,
505                    firing_relation: RelationIdentity::from_legacy_name(&event.table).map_err(
506                        |error| {
507                            SQLError::Internal(format!(
508                                "decode deferred trigger relation `{}`: {error}",
509                                event.table
510                            ))
511                        },
512                    )?,
513                    table: event.table.clone(),
514                    event: event.event,
515                    old: event.old.clone(),
516                    new: event.new.clone(),
517                    trigger: trigger.clone(),
518                })?;
519            continue;
520        }
521        let transition_tables = match transition_table {
522            Some(table) if !trigger.definition.transition_relations.is_empty() => {
523                Some(queue.transitions(context, table)?)
524            }
525            _ => None,
526        };
527        let _ = invoke_trigger(
528            context,
529            TriggerInvocation {
530                table: &event.table,
531                trigger,
532                timing: TriggerTiming::After,
533                event: event.event,
534                row: true,
535                old: event.old.clone(),
536                new: event.new.clone(),
537            },
538            transition_tables.as_deref(),
539        )?;
540    }
541    for check in checks {
542        context.foreign_keys.run_foreign_key_check(check, queue)?;
543    }
544    Ok(())
545}
546
547#[derive(Clone)]
548pub struct DeferredConstraintTriggerEvent {
549    pub constraint: uqa_sql::catalog::constraints::ConstraintIdentity,
550    pub firing_relation: RelationIdentity,
551    pub table: String,
552    event: TriggerEvent,
553    old: Value,
554    new: Value,
555    pub trigger: uqa_sql::catalog::events::StoredTrigger,
556}
557
558pub fn fire_deferred_constraint_trigger_event(
559    context: &TriggerContext<'_>,
560    event: &DeferredConstraintTriggerEvent,
561) -> Result<()> {
562    let _ = invoke_trigger(
563        context,
564        TriggerInvocation {
565            table: &event.table,
566            trigger: &event.trigger,
567            timing: TriggerTiming::After,
568            event: event.event,
569            row: true,
570            old: event.old.clone(),
571            new: event.new.clone(),
572        },
573        None,
574    )?;
575    Ok(())
576}
577
578#[derive(serde::Serialize, serde::Deserialize)]
579pub struct AfterRowTriggerEvent {
580    table: String,
581    event: TriggerEvent,
582    #[serde(with = "events::values")]
583    old: Value,
584    #[serde(with = "events::values")]
585    new: Value,
586    /// Whether `old` and `new` hold the row's images, which a row with no user trigger to fire and no transition to capture leaves out.
587    captured: bool,
588    triggers: Vec<uqa_sql::catalog::events::StoredTrigger>,
589    /// The foreign key checks and referential actions the row queued, in the order of their internal triggers' names.
590    foreign_keys: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
591}
592
593pub struct AfterRowTriggerInput<'a> {
594    pub table: &'a str,
595    pub event: TriggerEvent,
596    pub old_doc_id: DocId,
597    pub new_doc_id: DocId,
598    pub old_document: Option<&'a Document>,
599    pub new_document: Option<&'a Document>,
600    pub updated_columns: &'a [String],
601    /// The foreign key checks and referential actions the row's change queues (`referential::checks`).
602    pub foreign_key_checks: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
603}
604
605impl AfterRowTriggerEvent {
606    pub fn prepare(
607        context: &TriggerContext<'_>,
608        input: AfterRowTriggerInput<'_>,
609    ) -> Result<Option<Self>> {
610        let AfterRowTriggerInput {
611            table,
612            event,
613            old_doc_id,
614            new_doc_id,
615            old_document,
616            new_document,
617            updated_columns,
618            mut foreign_key_checks,
619        } = input;
620        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
621        let candidates = row_triggers::resolve(
622            context,
623            table,
624            TriggerTiming::After,
625            event,
626            Some(updated_columns),
627        )?;
628        let capture_transition =
629            transition_capture_required(context, table, event, updated_columns)?;
630        // The role is read when the row's events are queued, as `PostgreSQL` checks each trigger in `AfterTriggerSaveEvent`.
631        if !capture_transition
632            && !candidates
633                .iter()
634                .any(|trigger| row_triggers::fires(context, trigger))
635        {
636            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
637        }
638        let columns = trigger_column_metadata(context.catalog.trigger_relation_definitions(table)?);
639        let old = trigger_record(context, table, old_doc_id, old_document, false)?;
640        let new = trigger_record(context, table, new_doc_id, new_document, false)?;
641        let mut matching = Vec::new();
642        for trigger in candidates.iter() {
643            if row_triggers::fires(context, trigger)
644                && trigger_condition_matches(
645                    context,
646                    trigger.definition.when.as_ref(),
647                    &old,
648                    &new,
649                    &columns,
650                )?
651            {
652                let mut captured = trigger.clone();
653                // WHEN has already selected this event; firing must not retain or evaluate it again.
654                captured.definition.when = None;
655                matching.push(captured);
656            }
657        }
658        if matching.is_empty() && !capture_transition {
659            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
660        }
661        Ok(Some(Self {
662            table: table.to_string(),
663            event,
664            old,
665            new,
666            captured: true,
667            triggers: matching,
668            foreign_keys: foreign_key_checks,
669        }))
670    }
671
672    /// An event that only checks foreign keys and takes referential actions, for a row with no user trigger to fire and no transition to capture; `None` when the row queued neither.
673    pub fn foreign_key_checks(
674        table: &str,
675        event: TriggerEvent,
676        mut foreign_key_checks: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
677    ) -> Option<Self> {
678        if foreign_key_checks.is_empty() {
679            return None;
680        }
681        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
682        Some(Self {
683            table: table.to_string(),
684            event,
685            old: Value::Null,
686            new: Value::Null,
687            captured: false,
688            triggers: Vec::new(),
689            foreign_keys: foreign_key_checks,
690        })
691    }
692
693    pub fn prepare_transition_capture(
694        context: &TriggerContext<'_>,
695        input: AfterRowTriggerInput<'_>,
696    ) -> Result<Option<Self>> {
697        let AfterRowTriggerInput {
698            table,
699            event,
700            old_doc_id,
701            new_doc_id,
702            old_document,
703            new_document,
704            updated_columns,
705            foreign_key_checks,
706        } = input;
707        if !transition_capture_required(context, table, event, updated_columns)? {
708            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
709        }
710        let old = match old_document {
711            Some(document) => trigger_record(context, table, old_doc_id, Some(document), false)?,
712            None => Value::Null,
713        };
714        let new = match new_document {
715            Some(document) => trigger_record(context, table, new_doc_id, Some(document), false)?,
716            None => Value::Null,
717        };
718        let mut foreign_key_checks = foreign_key_checks;
719        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
720        Ok(Some(Self {
721            table: table.to_string(),
722            event,
723            old,
724            new,
725            captured: true,
726            triggers: Vec::new(),
727            foreign_keys: foreign_key_checks,
728        }))
729    }
730}