Skip to main content

uqa_execution/mutation/triggers/
queue.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! The AFTER trigger events of one statement, queued and fired as `PostgreSQL`'s `trigger.c` queues and fires the events of one query level.
8//!
9//! Every command of a statement queues into one queue: the primary command, its data-modifying WITH items, and the referential actions that the queued events run as they fire. A relation and an operation that the statement writes keep one state (`AfterTriggersTableData`): the rows its transition tables collect, whether its BEFORE STATEMENT triggers fired, and where its AFTER STATEMENT events wait in the queue. A later command on the same relation and operation therefore fires no second BEFORE STATEMENT trigger and moves the AFTER STATEMENT events to the end of the queue (`cancel_prior_stmt_triggers`), until a trigger reads the transition tables and closes the state, after which the rows start a new one.
10
11use super::context::TriggerContext;
12use super::{AfterRowTriggerEvent, TransitionTables};
13use std::collections::BTreeSet;
14use std::sync::Arc;
15use uqa_core::Value;
16use uqa_sql::ast::{TriggerEvent, TriggerTiming};
17use uqa_sql::error::Result;
18use uqa_sql::SQLError;
19
20/// A relation and operation that a command writes, with the columns an UPDATE sets, which its statement triggers fire for.
21#[derive(Debug, Clone)]
22pub struct StatementEvent {
23    pub relation: String,
24    pub event: TriggerEvent,
25    pub columns: Vec<String>,
26}
27
28impl StatementEvent {
29    pub fn new(relation: &str, event: TriggerEvent, columns: &[String]) -> Self {
30        Self {
31            relation: relation.to_string(),
32            event,
33            columns: columns.to_vec(),
34        }
35    }
36}
37
38/// The queued AFTER events of one statement.
39#[derive(Default)]
40pub struct AfterTriggerQueue {
41    state: parking_lot::Mutex<QueueState>,
42}
43
44#[derive(Default)]
45struct QueueState {
46    entries: Vec<QueueEntry>,
47    /// The first entry that has not fired.
48    next: usize,
49    tables: Vec<TableState>,
50}
51
52enum QueueEntry {
53    Row {
54        event: AfterRowTriggerEvent,
55        /// The state whose transition tables collected the row.
56        table: Option<usize>,
57    },
58    Statement {
59        statement: StatementEvent,
60        table: usize,
61    },
62    /// An entry that fired or that a later command cancelled.
63    Done,
64}
65
66/// The state of one relation and operation within the statement.
67struct TableState {
68    relation: String,
69    event: TriggerEvent,
70    /// The relation and its partitions, whose rows the transition tables collect.
71    sources: BTreeSet<String>,
72    capture: TransitionCapture,
73    /// A trigger has read the transition tables, which take no further rows.
74    closed: bool,
75    before_fired: bool,
76    /// Where the AFTER STATEMENT events of the state were queued, from which a later command cancels them.
77    statements_from: Option<usize>,
78    old_rows: Vec<Value>,
79    new_rows: Vec<Value>,
80    transitions: Option<Arc<TransitionTables>>,
81}
82
83/// Which images of its rows a relation's triggers read as transition tables.
84#[derive(Clone, Copy, Default)]
85struct TransitionCapture {
86    old: bool,
87    new: bool,
88}
89
90impl QueueState {
91    /// The open state of `relation` and `event`, created when every earlier one was closed (`GetAfterTriggersTableData`).
92    fn open_table(
93        &mut self,
94        context: &TriggerContext<'_>,
95        relation: &str,
96        event: TriggerEvent,
97    ) -> Result<usize> {
98        let relation = context
99            .relations
100            .try_resolve_table_name(relation)
101            .map_err(|error| SQLError::Internal(format!("resolve trigger relation: {error}")))?
102            .unwrap_or_else(|| relation.to_string());
103        if let Some(index) = self
104            .tables
105            .iter()
106            .position(|table| !table.closed && table.event == event && table.relation == relation)
107        {
108            return Ok(index);
109        }
110        let mut capture = TransitionCapture::default();
111        for row in [false, true] {
112            for trigger in
113                context
114                    .catalog
115                    .triggers_for(&relation, TriggerTiming::After, event, row, &[])?
116            {
117                capture.old |= trigger.definition.old_transition_table().is_some();
118                capture.new |= trigger.definition.new_transition_table().is_some();
119            }
120        }
121        // Only a relation whose triggers read transition tables collects rows, and a view has no partitions to collect them from.
122        let sources = if capture.old || capture.new {
123            context
124                .catalog
125                .hierarchy_scan_tables(&relation, true)?
126                .into_iter()
127                .collect()
128        } else {
129            BTreeSet::new()
130        };
131        self.tables.push(TableState {
132            relation,
133            event,
134            sources,
135            capture,
136            closed: false,
137            before_fired: false,
138            statements_from: None,
139            old_rows: Vec::new(),
140            new_rows: Vec::new(),
141            transitions: None,
142        });
143        Ok(self.tables.len() - 1)
144    }
145
146    /// Cancel the AFTER STATEMENT events that an earlier command queued for `table` and that have not fired.
147    fn cancel_prior_statements(&mut self, table: usize) {
148        let Some(from) = self.tables[table].statements_from else {
149            return;
150        };
151        for entry in self.entries.iter_mut().skip(from.max(self.next)) {
152            if matches!(entry, QueueEntry::Statement { table: queued, .. } if *queued == table) {
153                *entry = QueueEntry::Done;
154            }
155        }
156    }
157
158    /// Take the next entry to fire, leaving it done.
159    fn take_next(&mut self) -> Option<QueueEntry> {
160        while self.next < self.entries.len() {
161            let entry = std::mem::replace(&mut self.entries[self.next], QueueEntry::Done);
162            self.next += 1;
163            if !matches!(entry, QueueEntry::Done) {
164                return Some(entry);
165            }
166        }
167        None
168    }
169}
170
171impl AfterTriggerQueue {
172    /// Fire the BEFORE STATEMENT triggers of `statement` unless the statement already fired them for its open state (`before_stmt_triggers_fired`).
173    pub fn fire_before_statement(
174        &self,
175        context: &TriggerContext<'_>,
176        statement: &StatementEvent,
177    ) -> Result<()> {
178        let fire = {
179            let mut state = self.state.lock();
180            let table = state.open_table(context, &statement.relation, statement.event)?;
181            !std::mem::replace(&mut state.tables[table].before_fired, true)
182        };
183        if fire {
184            super::fire_statement_triggers(
185                context,
186                &statement.relation,
187                TriggerTiming::Before,
188                statement.event,
189                &statement.columns,
190            )?;
191        }
192        Ok(())
193    }
194
195    /// Queue the AFTER events of one command: the events of its rows, whose images join the transition tables of the statement event they belong to, then an AFTER STATEMENT event for each of `statements`, which replaces the one an earlier command queued for the same state.
196    pub fn queue_command(
197        &self,
198        context: &TriggerContext<'_>,
199        statements: &[StatementEvent],
200        rows: Vec<AfterRowTriggerEvent>,
201    ) -> Result<()> {
202        let mut state = self.state.lock();
203        let tables = statements
204            .iter()
205            .map(|statement| state.open_table(context, &statement.relation, statement.event))
206            .collect::<Result<Vec<_>>>()?;
207        for event in rows {
208            let table = if event.captured {
209                statements
210                    .iter()
211                    .zip(&tables)
212                    .find(|(statement, table)| {
213                        statement.event == event.event
214                            && state.tables[**table].sources.contains(&event.table)
215                    })
216                    .map(|(_, table)| *table)
217            } else {
218                None
219            };
220            if let Some(table) = table {
221                let target = &mut state.tables[table];
222                if target.capture.old && !matches!(event.old, Value::Null) {
223                    target.old_rows.push(event.old.clone());
224                }
225                if target.capture.new && !matches!(event.new, Value::Null) {
226                    target.new_rows.push(event.new.clone());
227                }
228            }
229            state.entries.push(QueueEntry::Row { event, table });
230        }
231        for (statement, table) in statements.iter().zip(tables) {
232            state.cancel_prior_statements(table);
233            let position = state.entries.len();
234            state.tables[table].statements_from = Some(position);
235            state.entries.push(QueueEntry::Statement {
236                statement: statement.clone(),
237                table,
238            });
239        }
240        Ok(())
241    }
242
243    /// Fire the queued events in order, with the events that the referential actions among them queue as they run (`afterTriggerInvokeEvents`).
244    pub fn fire(&self, context: &TriggerContext<'_>) -> Result<()> {
245        loop {
246            let Some(entry) = self.state.lock().take_next() else {
247                return Ok(());
248            };
249            match entry {
250                QueueEntry::Row { event, table } => {
251                    super::fire_after_row_trigger(context, &event, table, self)?;
252                }
253                QueueEntry::Statement { statement, table } => {
254                    self.fire_after_statement(context, &statement, table)?;
255                }
256                QueueEntry::Done => {}
257            }
258        }
259    }
260
261    fn fire_after_statement(
262        &self,
263        context: &TriggerContext<'_>,
264        statement: &StatementEvent,
265        table: usize,
266    ) -> Result<()> {
267        let triggers = context.catalog.triggers_for(
268            &statement.relation,
269            TriggerTiming::After,
270            statement.event,
271            false,
272            &statement.columns,
273        )?;
274        if triggers.is_empty() {
275            return Ok(());
276        }
277        let transitions = if triggers
278            .iter()
279            .any(|trigger| !trigger.definition.transition_relations.is_empty())
280        {
281            Some(self.transitions(context, table)?)
282        } else {
283            None
284        };
285        super::fire_statement_triggers_with_transition(
286            context,
287            &statement.relation,
288            TriggerTiming::After,
289            statement.event,
290            &statement.columns,
291            transitions.as_deref(),
292        )
293    }
294
295    /// The transition tables of `table`, which reading closes to further rows.
296    pub(super) fn transitions(
297        &self,
298        context: &TriggerContext<'_>,
299        table: usize,
300    ) -> Result<Arc<TransitionTables>> {
301        let mut state = self.state.lock();
302        let target = &mut state.tables[table];
303        target.closed = true;
304        if let Some(transitions) = &target.transitions {
305            return Ok(Arc::clone(transitions));
306        }
307        let old = target
308            .capture
309            .old
310            .then(|| {
311                super::transitions::materialize_transition_rows(
312                    context,
313                    &target.relation,
314                    std::mem::take(&mut target.old_rows),
315                )
316            })
317            .transpose()?;
318        let new = target
319            .capture
320            .new
321            .then(|| {
322                super::transitions::materialize_transition_rows(
323                    context,
324                    &target.relation,
325                    std::mem::take(&mut target.new_rows),
326                )
327            })
328            .transpose()?;
329        let transitions = Arc::new(TransitionTables { old, new });
330        target.transitions = Some(Arc::clone(&transitions));
331        Ok(transitions)
332    }
333}