Doc: document that triggers can break referential integrity.

User-written triggers can modify or block the effects of SQL update
and delete operations.  That includes operations that are executed
to implement foreign keys' referential integrity actions (such as
ON UPDATE SET NULL or ON DELETE CASCADE).  Therefore it's possible
for a misdesigned trigger to result in a database state that violates
the foreign key constraint.

While this isn't great, the alternatives seem worse: in particular,
refusing to fire triggers for such updates would break many valuable
use-cases.  We could also try to recheck the constraint after the
action, but that'd roughly double the already-high cost of FK
constraint enforcement, for no benefit in normal cases.  So we've
always considered that it's on the trigger programmer's head to
avoid breaking RI actions.  This was never documented anywhere,
though.  Add a para to the Triggers chapter to explain it.

Laurenz Albe, David Johnston, Tom Lane

Discussion: https://postgr.es/m/b81fe38fcc25a81be6e2e5b3fc1ff624130762fa[email protected]

diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index a5390ff64430e6150fa2e2f325d56f20c9252057..31626536a2e290d91b05acfaa9692d29cf2089de 100644 (file)
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -354,6 +354,17 @@
     to avoid infinite recursion in such scenarios.
    </para>
 
+   <para>
+    If a foreign key constraint specifies referential actions (that
+    is, cascading updates or deletes), those actions are performed via
+    ordinary SQL update or delete commands on the referencing table.
+    In particular, any triggers that exist on the referencing table
+    will be fired for those changes.  If such a trigger modifies or
+    blocks the effect of one of these commands, the end result could
+    be to break referential integrity.  It is the trigger programmer's
+    responsibility to avoid that.
+   </para>
+
    <para>
     <indexterm>
      <primary>trigger</primary>