From 393cdf38d812b337b51e3f5ca2af6ca052ed1b17 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Wed, 5 May 2021 11:53:38 +0200
Subject: [PATCH] Document how triggers interact with transactions

Clarify that triggers are always executed as part of the same
transaction as the triggering statement, with all consequences.

Add an index term for constraint triggers and mention them
in the documentation of trigger behavior.
---
 doc/src/sgml/ref/create_trigger.sgml | 4 ++++
 doc/src/sgml/trigger.sgml            | 7 ++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 561af989a4..e46b9e79db 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -175,6 +175,10 @@ CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name
   </para>
 
   <para>
+   <indexterm>
+    <primary>trigger</primary>
+    <secondary>constraint trigger</secondary>
+   </indexterm>
    When the <literal>CONSTRAINT</literal> option is specified, this command creates a
    <firstterm>constraint trigger</firstterm>.  This is the same as a regular trigger
    except that the timing of the trigger firing can be adjusted using
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 4a0e74652f..0c8cc8d0fe 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -47,7 +47,9 @@
     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.
+    event.  All triggers are executed as part of the same transaction as
+    the statement that triggered them, so if either the statement or the
+    trigger causes an error, the effects of both will be rolled back.
    </para>
 
    <para>
@@ -115,6 +117,9 @@
     <literal>BEFORE</literal> triggers fire immediately before a particular row is
     operated on, while row-level <literal>AFTER</literal> triggers fire at the end of
     the statement (but before any statement-level <literal>AFTER</literal> triggers).
+    The execution of <literal>AFTER</literal> triggers can also be deferred to the
+    end of the transaction if they were defined as
+    <firstterm>constraint triggers</firstterm>.
     These types of triggers may only be defined on tables and
     foreign tables, not views.
     <literal>INSTEAD OF</literal> triggers may only be
-- 
2.26.3