diff options
Diffstat (limited to 'doc/src/sgml/trigger.sgml')
| -rw-r--r-- | doc/src/sgml/trigger.sgml | 54 |
1 files changed, 29 insertions, 25 deletions
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index 950245d19a2..a16256056f0 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -41,17 +41,13 @@ On tables and foreign tables, triggers can be defined to execute either before or after any <command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command> operation, either once per modified row, - or once per <acronym>SQL</acronym> statement. If an - <command>INSERT</command> contains an <literal>ON CONFLICT DO UPDATE</> - clause, it is possible that the effects of a BEFORE insert trigger and - a BEFORE update trigger can both be applied together, if a reference to - an <varname>EXCLUDED</> column appears. <command>UPDATE</command> - triggers can moreover be set to fire only if certain columns are - mentioned in the <literal>SET</literal> clause of the - <command>UPDATE</command> statement. Triggers can also fire for - <command>TRUNCATE</command> statements. If a trigger event occurs, + or once per <acronym>SQL</acronym> statement. + <command>UPDATE</command> triggers can moreover be set to fire only if + certain columns are mentioned in the <literal>SET</literal> clause of + the <command>UPDATE</command> statement. Triggers can also fire + for <command>TRUNCATE</command> statements. If a trigger event occurs, the trigger's function is called at the appropriate time to handle the - event. Foreign tables do not support the TRUNCATE statement at all. + event. </para> <para> @@ -97,10 +93,7 @@ two types of triggers are sometimes called <firstterm>row-level</> triggers and <firstterm>statement-level</> triggers, respectively. Triggers on <command>TRUNCATE</command> may only be - defined at statement level. On views, triggers that fire before or - after may only be defined at statement level, while triggers that fire - instead of an <command>INSERT</command>, <command>UPDATE</command>, - or <command>DELETE</command> may only be defined at row level. + defined at statement level, not per-row. </para> <para> @@ -117,9 +110,9 @@ operated on, while row-level <literal>AFTER</> triggers fire at the end of the statement (but before any statement-level <literal>AFTER</> triggers). These types of triggers may only be defined on non-partitioned tables and - foreign tables. Row-level <literal>INSTEAD OF</> triggers may only be - defined on views, and fire immediately as each row in the view is - identified as needing to be operated on. + foreign tables, not views. <literal>INSTEAD OF</> triggers may only be + defined on views, and only at row level; they fire immediately as each + row in the view is identified as needing to be operated on. </para> <para> @@ -132,18 +125,19 @@ <para> If an <command>INSERT</command> contains an <literal>ON CONFLICT - DO UPDATE</> clause, it is possible that the effects of all - row-level <literal>BEFORE</> <command>INSERT</command> triggers - and all row-level <literal>BEFORE</literal> <command>UPDATE</command> triggers can + DO UPDATE</> clause, it is possible that the effects of + row-level <literal>BEFORE</> <command>INSERT</command> triggers and + row-level <literal>BEFORE</literal> <command>UPDATE</command> triggers can both be applied in a way that is apparent from the final state of the updated row, if an <varname>EXCLUDED</> column is referenced. There need not be an <varname>EXCLUDED</> column reference for - both sets of row-level <literal>BEFORE</literal> triggers to execute, though. The + both sets of row-level <literal>BEFORE</literal> triggers to execute, + though. The possibility of surprising outcomes should be considered when there are both <literal>BEFORE</> <command>INSERT</command> and <literal>BEFORE</> <command>UPDATE</command> row-level triggers - that both affect a row being inserted/updated (this can still be - problematic if the modifications are more or less equivalent if + that change a row being inserted/updated (this can be + problematic even if the modifications are more or less equivalent, if they're not also idempotent). Note that statement-level <command>UPDATE</command> triggers are executed when <literal>ON CONFLICT DO UPDATE</> is specified, regardless of whether or not @@ -314,8 +308,18 @@ <varname>NEW</varname> row for <command>INSERT</command> and <command>UPDATE</command> triggers, and/or the <varname>OLD</varname> row for <command>UPDATE</command> and <command>DELETE</command> triggers. - Statement-level triggers do not currently have any way to examine the - individual row(s) modified by the statement. + </para> + + <para> + By default, statement-level triggers do not have any way to examine the + individual row(s) modified by the statement. But an <literal>AFTER + STATEMENT</> trigger can request that <firstterm>transition tables</> + be created to make the sets of affected rows available to the trigger. + <literal>AFTER ROW</> triggers can also request transition tables, so + that they can see the total changes in the table as well as the change in + the individual row they are currently being fired for. The syntax for + examining the transition tables again depends on the programming language + that is being used. </para> </sect1> |