From c1474f943b8fdb0f496c30cd87339e18d6e13a20 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Tue, 31 Oct 2023 11:38:59 +0100
Subject: [PATCH] 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
Discussion: https://postgr.es/m/b81fe38fcc25a81be6e2e5b3fc1ff624130762fa.camel%40cybertec.at
---
 doc/src/sgml/ddl.sgml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 075ff32991..2c1c06702e 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1224,6 +1224,19 @@ 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
+     responsibility of the user to write triggers so that such problems are
+     avoided.
+    </para>
+   </note>
   </sect2>
 
   <sect2 id="ddl-constraints-exclusion">
-- 
2.41.0