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 queue;
128mod transitions;
129pub use transitions::{transition_capture_required, TransitionTables};
130
131mod row_triggers;
132mod rows;
133use rows::{
134    trigger_column_metadata, trigger_document, trigger_record, TriggerColumnMetadata,
135    TriggerVariableResolver,
136};
137
138fn operation_name(event: TriggerEvent) -> &'static str {
139    match event {
140        TriggerEvent::Insert => "INSERT",
141        TriggerEvent::Update => "UPDATE",
142        TriggerEvent::Delete => "DELETE",
143        TriggerEvent::Truncate => "TRUNCATE",
144    }
145}
146
147fn timing_name(timing: TriggerTiming) -> &'static str {
148    match timing {
149        TriggerTiming::Before => "BEFORE",
150        TriggerTiming::After => "AFTER",
151        TriggerTiming::InsteadOf => "INSTEAD OF",
152    }
153}
154
155fn trigger_condition_matches(
156    context: &TriggerContext<'_>,
157    condition: Option<&uqa_sql::ast::Expr>,
158    old: &Value,
159    new: &Value,
160    columns: &BTreeMap<String, TriggerColumnMetadata>,
161) -> Result<bool> {
162    let Some(condition) = condition else {
163        return Ok(true);
164    };
165    let condition = bind_expr(
166        condition,
167        &mut TriggerVariableResolver { old, new, columns },
168    )?;
169    Ok(uqa_sql::expr::truthy(
170        &context.expressions.evaluate(&condition)?,
171    ))
172}
173
174struct TriggerInvocation<'a> {
175    table: &'a str,
176    trigger: &'a uqa_sql::catalog::events::StoredTrigger,
177    timing: TriggerTiming,
178    event: TriggerEvent,
179    row: bool,
180    old: Value,
181    new: Value,
182}
183
184fn invoke_trigger(
185    context: &TriggerContext<'_>,
186    invocation: TriggerInvocation<'_>,
187    transition_tables: Option<&TransitionTables>,
188) -> Result<Value> {
189    let relation = RelationIdentity::from_legacy_name(invocation.table).map_err(|error| {
190        SQLError::Internal(format!(
191            "decode trigger relation `{}`: {error}",
192            invocation.table
193        ))
194    })?;
195    let function = context.routines.resolve_bound_trigger_function(
196        &invocation.trigger.definition.function,
197        invocation.trigger.function_object_id,
198    )?;
199    let _transition_scope = match transition_tables {
200        Some(tables) => tables.enter(&invocation.trigger.definition)?,
201        None if invocation
202            .trigger
203            .definition
204            .transition_relations
205            .is_empty() =>
206        {
207            TransitionRelationScope::empty()
208        }
209        None => {
210            return Err(SQLError::Internal(format!(
211                "trigger `{}` requested unavailable transition tables",
212                invocation.trigger.definition.name
213            )))
214        }
215    };
216    let _depth = TriggerDepthScope::enter();
217    context.routines.execute_trigger_routine(
218        &function,
219        &TriggerRoutineContext {
220            row_schema: uqa_sql::RowSchema::with_column_metadata(
221                None,
222                context
223                    .catalog
224                    .trigger_relation_definitions(invocation.table)?
225                    .into_iter()
226                    .map(|column| (column.name, Some(column.ty), column.collation_oid)),
227            ),
228            old: invocation.old,
229            new: invocation.new,
230            name: invocation.trigger.definition.name.clone(),
231            when: timing_name(invocation.timing).into(),
232            level: if invocation.row { "ROW" } else { "STATEMENT" }.into(),
233            operation: operation_name(invocation.event).into(),
234            relation_oid: crate::catalog::projection::event_relation_oid(
235                &context.projection,
236                invocation.table,
237            )?,
238            table_name: relation.name,
239            table_schema: relation.schema,
240            arguments: invocation.trigger.definition.arguments.clone(),
241        },
242    )
243}
244
245fn positional_trigger_record(
246    columns: &[(String, uqa_sql::ast::ColumnType)],
247    values: Option<&[Value]>,
248) -> Result<Value> {
249    if values.is_some_and(|values| values.len() != columns.len()) {
250        return Err(SQLError::Internal(
251            "INSTEAD OF trigger row does not match the view row type".into(),
252        ));
253    }
254    Ok(Value::Record(
255        columns
256            .iter()
257            .enumerate()
258            .map(|(position, (name, _))| {
259                (
260                    name.clone(),
261                    values
262                        .and_then(|values| values.get(position))
263                        .cloned()
264                        .unwrap_or(Value::Null),
265                )
266            })
267            .collect::<Vec<_>>()
268            .into(),
269    ))
270}
271
272fn normalize_instead_of_trigger_record(
273    columns: &[(String, uqa_sql::ast::ColumnType)],
274    value: Value,
275) -> Result<Option<Vec<Value>>> {
276    let fields = match value {
277        Value::Null => return Ok(None),
278        Value::Record(fields) => fields.into_iter().collect::<BTreeMap<_, _>>(),
279        _ => {
280            return Err(SQLError::Routine {
281                sqlstate: "39P01".into(),
282                message: "trigger function returned non-composite value".into(),
283            })
284        }
285    };
286    if let Some(unknown) = fields
287        .keys()
288        .find(|name| !columns.iter().any(|(column, _)| column == *name))
289    {
290        return Err(SQLError::UnknownColumn(unknown.clone()));
291    }
292    // The routine result has already passed descriptor validation; these values are admitted, not new input.
293    Ok(Some(
294        columns
295            .iter()
296            .map(|(name, _)| fields.get(name).cloned().unwrap_or(Value::Null))
297            .collect(),
298    ))
299}
300
301/// 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.
302pub fn fire_instead_of_row_triggers(
303    context: &TriggerContext<'_>,
304    view: &str,
305    event: TriggerEvent,
306    old_values: Option<&[Value]>,
307    new_values: Option<&[Value]>,
308    updated_columns: &[String],
309) -> Result<Option<Vec<Value>>> {
310    let columns = context.catalog.rule_relation_columns(view)?;
311    let old = positional_trigger_record(&columns, old_values)?;
312    let mut new = positional_trigger_record(&columns, new_values)?;
313    let triggers = context.catalog.triggers_for(
314        view,
315        TriggerTiming::InsteadOf,
316        event,
317        true,
318        updated_columns,
319    )?;
320    if triggers.is_empty()
321        && !context
322            .catalog
323            .has_trigger_definition(view, TriggerTiming::InsteadOf, event, true)?
324    {
325        return Err(SQLError::Routine {
326            sqlstate: "55000".into(),
327            message: format!(
328                "cannot {} view \"{}\": no active INSTEAD OF trigger",
329                operation_name(event).to_ascii_lowercase(),
330                RelationIdentity::from_legacy_name(view)
331                    .map_or_else(|_| view.to_string(), |relation| relation.name)
332            ),
333        });
334    }
335    for trigger in triggers {
336        let returned = invoke_trigger(
337            context,
338            TriggerInvocation {
339                table: view,
340                trigger: &trigger,
341                timing: TriggerTiming::InsteadOf,
342                event,
343                row: true,
344                old: old.clone(),
345                new: new.clone(),
346            },
347            None,
348        )?;
349        let Some(values) = normalize_instead_of_trigger_record(&columns, returned)? else {
350            return Ok(None);
351        };
352        if event != TriggerEvent::Delete {
353            new = positional_trigger_record(&columns, Some(&values))?;
354        }
355    }
356    let final_record = if event == TriggerEvent::Delete {
357        old
358    } else {
359        new
360    };
361    normalize_instead_of_trigger_record(&columns, final_record)
362}
363
364pub fn fire_statement_triggers(
365    context: &TriggerContext<'_>,
366    table: &str,
367    timing: TriggerTiming,
368    event: TriggerEvent,
369    updated_columns: &[String],
370) -> Result<()> {
371    fire_statement_triggers_with_transition(context, table, timing, event, updated_columns, None)
372}
373
374fn fire_statement_triggers_with_transition(
375    context: &TriggerContext<'_>,
376    table: &str,
377    timing: TriggerTiming,
378    event: TriggerEvent,
379    updated_columns: &[String],
380    transition_tables: Option<&TransitionTables>,
381) -> Result<()> {
382    for trigger in context
383        .catalog
384        .triggers_for(table, timing, event, false, updated_columns)?
385    {
386        let _ = invoke_trigger(
387            context,
388            TriggerInvocation {
389                table,
390                trigger: &trigger,
391                timing,
392                event,
393                row: false,
394                old: Value::Null,
395                new: Value::Null,
396            },
397            transition_tables,
398        )?;
399    }
400    Ok(())
401}
402
403/// 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.
404pub fn has_before_row_triggers(
405    context: &TriggerContext<'_>,
406    table: &str,
407    event: TriggerEvent,
408) -> Result<bool> {
409    Ok(!row_triggers::resolve(context, table, TriggerTiming::Before, event, None)?.is_empty())
410}
411
412pub fn fire_before_row_triggers(
413    context: &TriggerContext<'_>,
414    table: &str,
415    event: TriggerEvent,
416    doc_id: DocId,
417    old_document: Option<&Document>,
418    new_document: Option<&Document>,
419    updated_columns: &[String],
420) -> Result<Option<Document>> {
421    let triggers = row_triggers::resolve(
422        context,
423        table,
424        TriggerTiming::Before,
425        event,
426        Some(updated_columns),
427    )?;
428    let original = if event == TriggerEvent::Delete {
429        old_document
430    } else {
431        new_document
432    };
433    if !triggers
434        .iter()
435        .any(|trigger| row_triggers::fires(context, trigger))
436    {
437        return Ok(original.cloned());
438    }
439    let columns = trigger_column_metadata(context.catalog.trigger_relation_definitions(table)?);
440    let old = trigger_record(context, table, doc_id, old_document, false)?;
441    let mut new = trigger_record(context, table, doc_id, new_document, true)?;
442    let mut invoked = false;
443    for trigger in triggers.iter() {
444        // An earlier trigger of this row may have changed the role.
445        if !row_triggers::fires(context, trigger)
446            || !trigger_condition_matches(
447                context,
448                trigger.definition.when.as_ref(),
449                &old,
450                &new,
451                &columns,
452            )?
453        {
454            continue;
455        }
456        invoked = true;
457        let returned = invoke_trigger(
458            context,
459            TriggerInvocation {
460                table,
461                trigger,
462                timing: TriggerTiming::Before,
463                event,
464                row: true,
465                old: old.clone(),
466                new: new.clone(),
467            },
468            None,
469        )?;
470        if matches!(returned, Value::Null) {
471            return Ok(None);
472        }
473        if event != TriggerEvent::Delete {
474            new = returned;
475        }
476    }
477    if event == TriggerEvent::Delete || !invoked {
478        return Ok(original.cloned());
479    }
480    trigger_document(context, table, new)
481}
482
483/// 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.
484fn fire_after_row_trigger(
485    context: &TriggerContext<'_>,
486    event: &AfterRowTriggerEvent,
487    transition_table: Option<usize>,
488    queue: &queue::AfterTriggerQueue,
489) -> Result<()> {
490    let mut checks = event.foreign_keys.iter().peekable();
491    for trigger in &event.triggers {
492        while let Some(check) =
493            checks.next_if(|check| check.precedes_trigger(&trigger.definition.name))
494        {
495            context.foreign_keys.run_foreign_key_check(check, queue)?;
496        }
497        if trigger.definition.constraint
498            && context.deferrals.constraint_trigger_is_deferred(trigger)?
499        {
500            context
501                .deferrals
502                .defer_constraint_trigger_event(DeferredConstraintTriggerEvent {
503                    constraint: trigger.constraint_identity()?,
504                    firing_relation: RelationIdentity::from_legacy_name(&event.table).map_err(
505                        |error| {
506                            SQLError::Internal(format!(
507                                "decode deferred trigger relation `{}`: {error}",
508                                event.table
509                            ))
510                        },
511                    )?,
512                    table: event.table.clone(),
513                    event: event.event,
514                    old: event.old.clone(),
515                    new: event.new.clone(),
516                    trigger: trigger.clone(),
517                })?;
518            continue;
519        }
520        let transition_tables = match transition_table {
521            Some(table) if !trigger.definition.transition_relations.is_empty() => {
522                Some(queue.transitions(context, table)?)
523            }
524            _ => None,
525        };
526        let _ = invoke_trigger(
527            context,
528            TriggerInvocation {
529                table: &event.table,
530                trigger,
531                timing: TriggerTiming::After,
532                event: event.event,
533                row: true,
534                old: event.old.clone(),
535                new: event.new.clone(),
536            },
537            transition_tables.as_deref(),
538        )?;
539    }
540    for check in checks {
541        context.foreign_keys.run_foreign_key_check(check, queue)?;
542    }
543    Ok(())
544}
545
546#[derive(Clone)]
547pub struct DeferredConstraintTriggerEvent {
548    pub constraint: uqa_sql::catalog::constraints::ConstraintIdentity,
549    pub firing_relation: RelationIdentity,
550    pub table: String,
551    event: TriggerEvent,
552    old: Value,
553    new: Value,
554    pub trigger: uqa_sql::catalog::events::StoredTrigger,
555}
556
557pub fn fire_deferred_constraint_trigger_event(
558    context: &TriggerContext<'_>,
559    event: &DeferredConstraintTriggerEvent,
560) -> Result<()> {
561    let _ = invoke_trigger(
562        context,
563        TriggerInvocation {
564            table: &event.table,
565            trigger: &event.trigger,
566            timing: TriggerTiming::After,
567            event: event.event,
568            row: true,
569            old: event.old.clone(),
570            new: event.new.clone(),
571        },
572        None,
573    )?;
574    Ok(())
575}
576
577pub struct AfterRowTriggerEvent {
578    table: String,
579    event: TriggerEvent,
580    old: Value,
581    new: Value,
582    /// 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.
583    captured: bool,
584    triggers: Vec<uqa_sql::catalog::events::StoredTrigger>,
585    /// The foreign key checks and referential actions the row queued, in the order of their internal triggers' names.
586    foreign_keys: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
587}
588
589pub struct AfterRowTriggerInput<'a> {
590    pub table: &'a str,
591    pub event: TriggerEvent,
592    pub old_doc_id: DocId,
593    pub new_doc_id: DocId,
594    pub old_document: Option<&'a Document>,
595    pub new_document: Option<&'a Document>,
596    pub updated_columns: &'a [String],
597    /// The foreign key checks and referential actions the row's change queues (`referential::checks`).
598    pub foreign_key_checks: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
599}
600
601impl AfterRowTriggerEvent {
602    pub fn prepare(
603        context: &TriggerContext<'_>,
604        input: AfterRowTriggerInput<'_>,
605    ) -> Result<Option<Self>> {
606        let AfterRowTriggerInput {
607            table,
608            event,
609            old_doc_id,
610            new_doc_id,
611            old_document,
612            new_document,
613            updated_columns,
614            mut foreign_key_checks,
615        } = input;
616        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
617        let candidates = row_triggers::resolve(
618            context,
619            table,
620            TriggerTiming::After,
621            event,
622            Some(updated_columns),
623        )?;
624        let capture_transition =
625            transition_capture_required(context, table, event, updated_columns)?;
626        // The role is read when the row's events are queued, as `PostgreSQL` checks each trigger in `AfterTriggerSaveEvent`.
627        if !capture_transition
628            && !candidates
629                .iter()
630                .any(|trigger| row_triggers::fires(context, trigger))
631        {
632            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
633        }
634        let columns = trigger_column_metadata(context.catalog.trigger_relation_definitions(table)?);
635        let old = trigger_record(context, table, old_doc_id, old_document, false)?;
636        let new = trigger_record(context, table, new_doc_id, new_document, false)?;
637        let mut matching = Vec::new();
638        for trigger in candidates.iter() {
639            if row_triggers::fires(context, trigger)
640                && trigger_condition_matches(
641                    context,
642                    trigger.definition.when.as_ref(),
643                    &old,
644                    &new,
645                    &columns,
646                )?
647            {
648                matching.push(trigger.clone());
649            }
650        }
651        if matching.is_empty() && !capture_transition {
652            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
653        }
654        Ok(Some(Self {
655            table: table.to_string(),
656            event,
657            old,
658            new,
659            captured: true,
660            triggers: matching,
661            foreign_keys: foreign_key_checks,
662        }))
663    }
664
665    /// 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.
666    pub fn foreign_key_checks(
667        table: &str,
668        event: TriggerEvent,
669        mut foreign_key_checks: Vec<crate::mutation::referential::checks::ForeignKeyCheck>,
670    ) -> Option<Self> {
671        if foreign_key_checks.is_empty() {
672            return None;
673        }
674        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
675        Some(Self {
676            table: table.to_string(),
677            event,
678            old: Value::Null,
679            new: Value::Null,
680            captured: false,
681            triggers: Vec::new(),
682            foreign_keys: foreign_key_checks,
683        })
684    }
685
686    pub fn prepare_transition_capture(
687        context: &TriggerContext<'_>,
688        input: AfterRowTriggerInput<'_>,
689    ) -> Result<Option<Self>> {
690        let AfterRowTriggerInput {
691            table,
692            event,
693            old_doc_id,
694            new_doc_id,
695            old_document,
696            new_document,
697            updated_columns,
698            foreign_key_checks,
699        } = input;
700        if !transition_capture_required(context, table, event, updated_columns)? {
701            return Ok(Self::foreign_key_checks(table, event, foreign_key_checks));
702        }
703        let old = match old_document {
704            Some(document) => trigger_record(context, table, old_doc_id, Some(document), false)?,
705            None => Value::Null,
706        };
707        let new = match new_document {
708            Some(document) => trigger_record(context, table, new_doc_id, Some(document), false)?,
709            None => Value::Null,
710        };
711        let mut foreign_key_checks = foreign_key_checks;
712        crate::mutation::referential::checks::ForeignKeyCheck::sort(&mut foreign_key_checks);
713        Ok(Some(Self {
714            table: table.to_string(),
715            event,
716            old,
717            new,
718            captured: true,
719            triggers: Vec::new(),
720            foreign_keys: foreign_key_checks,
721        }))
722    }
723}