doc: Some additional information about when to use referential actions

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 94f745aed03c1ed0d91738b742e771203379d1c7..642ea2a70d04ccf73d4e3cbfb028e76409500177 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1062,6 +1062,27 @@ CREATE TABLE order_items (
     operation will fail.
    
 
+   
+    The appropriate choice of ON DELETE action depends on
+    what kinds of objects the related tables represent.  When the referencing
+    table represents something that is a component of what is represented by
+    the referenced table and cannot exist independently, then
+    CASCADE could be appropriate.  If the two tables
+    represent independent objects, then RESTRICT or
+    NO ACTION is more appropriate; an application that
+    actually wants to delete both objects would then have to be explicit about
+    this and run two delete options.  In the above example, order items are
+    part of an order, and it is convenient if they are deleted automatically
+    if an order is deleted.  But products and orders are different things, and
+    so making a deletion of a product automatically cause the deletion of some
+    order items could be considered problematic.  The actions SET
+    NULL or SET DEFAULT can be appropriate if a
+    foreign-key relationship represents optional information.  For example, if
+    the products table contained a reference to a product manager, and the
+    product manager entry gets deleted, then setting the product's product
+    manager to null or a default might be useful.
+   
+
    
     Analogous to ON DELETE there is also
     ON UPDATE which is invoked when a referenced