From f47c149edd529dc7f1f39977b3d01ee501e19fab Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Fri, 22 Dec 2023 12:33:40 +0100
Subject: [PATCH v3] Document foreign key internals

Warn the user that foreign keys are implemented as triggers, and
that user-defined triggers can interact with them and break
referential integrity.

Author: Laurenz Albe
Reviewed-by: David G. Johnston, Pavel Luzanov
Discussion: https://postgr.es/m/b81fe38fcc25a81be6e2e5b3fc1ff624130762fa.camel%40cybertec.at
---
 doc/src/sgml/ddl.sgml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index d2951cd754..03c5619e9e 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1224,6 +1224,18 @@ CREATE TABLE posts (
     syntax in the reference documentation for
     <xref linkend="sql-createtable"/>.
    </para>
+
+   <note>
+    <para>
+     Foreign key constraints are implemented as system triggers in
+     <productname>PostgreSQL</productname>.  As such, they are subject to the
+     trigger firing rules described in <xref linkend="trigger-definition"/>.
+     In particular, user-defined triggers on the referencing table can cancel
+     or modify the effects of cascading deletes or updates, thereby breaking
+     referential integrity.  This is not considered a bug, and it is the
+     trigger programmer's responsibility of avoid such problems.
+    </para>
+   </note>
   </sect2>
 
   <sect2 id="ddl-constraints-exclusion">
-- 
2.43.0