doc: clarify handling of ON CONFLICT with triggers

The previous wording was confusing.  Also move partitioning mention to a
more logical location.

Reported-by: [email protected]
Discussion: https://postgr.es/m/20170703200710[email protected]

Backpatch-through: master

diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 6e1f370b213b3099939ce206d8f71633362a7ca3..a5390ff64430e6150fa2e2f325d56f20c9252057 100644 (file)
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -132,29 +132,19 @@
    
 
    
-    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 INSERT contains an ON CONFLICT
+    DO UPDATE clause, it is possible for row-level
+    BEFORE INSERT and then
+    BEFORE UPDATE triggers
+    to be executed on triggered rows.  Such interactions can be
+    complex if the triggers are not idempotent because change made by
+    BEFORE INSERT triggers will be
+    seen by BEFORE UPDATE triggers,
+    including changes to EXCLUDED columns.
    
 
    
-    If an INSERT contains an ON CONFLICT
-    DO UPDATE clause, it is possible that the effects of
-    row-level BEFORE INSERT triggers and
-    row-level BEFORE UPDATE triggers can
-    both be applied in a way that is apparent from the final state of
-    the updated row, if an EXCLUDED column is referenced.
-    There need not be an EXCLUDED column reference for
-    both sets of row-level BEFORE triggers to execute,
-    though.  The
-    possibility of surprising outcomes should be considered when there
-    are both BEFORE INSERT and
-    BEFORE UPDATE 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
     UPDATE triggers are executed when ON
     CONFLICT DO UPDATE is specified, regardless of whether or not
     any rows were affected by the UPDATE (and
@@ -169,6 +159,14 @@
     triggers.
    
 
+   
+    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 UPDATE on a partitioned table causes a row to move
     to another partition, it will be performed as a DELETE