Date: Fri, 24 Nov 2023 13:14:11 -0500
From: Bruce Momjian <bruce@momjian.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Peter Geoghegan <pg@bowt.ie>, neil@fairwindsoft.com,
	PostgreSQL-documentation <pgsql-docs@postgresql.org>,
	Andres Freund <andres@anarazel.de>,
	Heikki Linnakangas <heikki.linnakangas@iki.fi>
Subject: Re: [DOCS] Confusing Trigger Docs.
Message-ID: <ZWDn87yyRnC-5ybw@momjian.us>
References: <20170703200710.27956.64565@wrigleys.postgresql.org>
 <20170831132544.GC2355@momjian.us>
 <CAH2-WzkiHHJue-DRt_zdSvKXJFUU=7CNdxkA31m1Vmyr5G2Jcg@mail.gmail.com>
 <ZV1g6BsylqHAFYEL@momjian.us>
 <ef350902caa5bdb5a26e6152e75c9509a47acd5b.camel@cybertec.at>
 <ZV5u5uEtVwBjQqQ4@momjian.us>
 <CAH2-Wzk+VWp6dTTcBX329w+nh9zjkCE4=AapGeVtxpd7j_Dqug@mail.gmail.com>
 <103ef5b01c801d372f8aa2353aecf4fc8364bd6c.camel@cybertec.at>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="LKtGBDZMoTW0ecJK"
Content-Disposition: inline
In-Reply-To: <103ef5b01c801d372f8aa2353aecf4fc8364bd6c.camel@cybertec.at>
Archived-At: 
 <https://www.postgresql.org/message-id/ZWDn87yyRnC-5ybw%40momjian.us>
Precedence: bulk


--LKtGBDZMoTW0ecJK
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Thu, Nov 23, 2023 at 08:36:34AM +0100, Laurenz Albe wrote:
> On Wed, 2023-11-22 at 14:49 -0800, Peter Geoghegan wrote:
> > I don't think that your proposed wording for this is an improvement.
> 
> Well, the existing wording is impenetrable even for someone with some
> PostgreSQL knowledge, like me.

I moved the parition pagagraph to a more logical location and tried to
clarify the new paragraph to be more targeted on the goal, patch
attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

--LKtGBDZMoTW0ecJK
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="excluded.diff"

diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 6e1f370b21..a5390ff644 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -132,29 +132,19 @@
    </para>
 
    <para>
-    A statement that targets a parent table in an inheritance or partitioning
-    hierarchy does not cause the statement-level triggers of affected child
-    tables to be fired; only the parent table's statement-level triggers are
-    fired.  However, row-level triggers of any affected child tables will be
-    fired.
+    If an <command>INSERT</command> contains an <literal>ON CONFLICT
+    DO UPDATE</literal> clause, it is possible for row-level
+    <literal>BEFORE</literal> <command>INSERT</command> and then
+    <literal>BEFORE</literal> <command>UPDATE</command> triggers
+    to be executed on triggered rows.  Such interactions can be
+    complex if the triggers are not idempotent because change made by
+    <literal>BEFORE</literal> <command>INSERT</command> triggers will be
+    seen by <literal>BEFORE</literal> <command>UPDATE</command> triggers,
+    including changes to <varname>EXCLUDED</varname> columns.
    </para>
 
    <para>
-    If an <command>INSERT</command> contains an <literal>ON CONFLICT
-    DO UPDATE</literal> clause, it is possible that the effects of
-    row-level <literal>BEFORE</literal> <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</varname> column is referenced.
-    There need not be an <varname>EXCLUDED</varname> column reference for
-    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</literal> <command>INSERT</command> and
-    <literal>BEFORE</literal> <command>UPDATE</command> row-level triggers
-    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
+    Note that statement-level
     <command>UPDATE</command> triggers are executed when <literal>ON
     CONFLICT DO UPDATE</literal> is specified, regardless of whether or not
     any rows were affected by the <command>UPDATE</command> (and
@@ -169,6 +159,14 @@
     triggers.
    </para>
 
+   <para>
+    A statement that targets a parent table in an inheritance or partitioning
+    hierarchy does not cause the statement-level triggers of affected child
+    tables to be fired; only the parent table's statement-level triggers are
+    fired.  However, row-level triggers of any affected child tables will be
+    fired.
+   </para>
+
    <para>
     If an <command>UPDATE</command> on a partitioned table causes a row to move
     to another partition, it will be performed as a <command>DELETE</command>

--LKtGBDZMoTW0ecJK--