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