Document that dependency tracking doesn't consider function bodies.

If there's anyplace in our SGML docs that explains this behavior, I can't
find it right at the moment.  Add an explanation in "Dependency Tracking"
which seems like the authoritative place for such a discussion.  Per
gripe from Michelle Schwan.

While at it, update this section's example of a dependency-related
error message: they last looked like that in 8.3.  And remove the
explanation of dependency updates from pre-7.3 installations, which
is probably no longer worth anybody's brain cells to read.

The bogus error message example seems like an actual documentation bug,
so back-patch to all supported branches.

Discussion: <20160620160047[email protected]>

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index f2055b0d587d9371c0608d7f6ff135665ecfc890..954c3a9b9e4dd715c52ac50216c1dc8b006baab1 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3571,14 +3571,14 @@ ANALYZE measurement;
    To ensure the integrity of the entire database structure,
    PostgreSQL makes sure that you cannot
    drop objects that other objects still depend on.  For example,
-   attempting to drop the products table we had considered in 
+   attempting to drop the products table we considered in 
    linkend="ddl-constraints-fk">, with the orders table depending on
-   it, would result in an error message such as this:
+   it, would result in an error message like this:
 
 DROP TABLE products;
 
-NOTICE:  constraint orders_product_no_fkey on table orders depends on table products
 ERROR:  cannot drop table products because other objects depend on it
+DETAIL:  constraint orders_product_no_fkey on table orders depends on table products
 HINT:  Use DROP ... CASCADE to drop the dependent objects too.
 
    The error message contains a useful hint: if you do not want to
@@ -3589,11 +3589,12 @@ DROP TABLE products CASCADE;
    and all the dependent objects will be removed.  In this case, it
    doesn't remove the orders table, it only removes the foreign key
    constraint.  (If you want to check what DROP ... CASCADE will do,
-   run DROP without CASCADE and read the NOTICE messages.)
+   run DROP without CASCADE and read the
+   DETAIL output.)
   
 
   
-   All drop commands in PostgreSQL> support
+   All DROP commands in PostgreSQL> support
    specifying CASCADE.  Of course, the nature of
    the possible dependencies varies with the type of the object.  You
    can also write RESTRICT instead of
@@ -3605,21 +3606,43 @@ DROP TABLE products CASCADE;
    
     According to the SQL standard, specifying either
     RESTRICT or CASCADE is
-    required.  No database system actually enforces that rule, but
-    whether the default behavior is RESTRICT or
-    CASCADE varies across systems.
+    required in a DROP command.  No database system actually
+    enforces that rule, but whether the default behavior
+    is RESTRICT or CASCADE varies
+    across systems.
    
   
 
-  
-   
-    Foreign key constraint dependencies and serial column dependencies
-    from PostgreSQL versions prior to 7.3
-    are not maintained or created during the
-    upgrade process.  All other dependency types will be properly
-    created during an upgrade from a pre-7.3 database.
-   
-  
+  
+   For user-defined functions, PostgreSQL tracks
+   dependencies associated with a function's externally-visible properties,
+   such as its argument and result types, but not dependencies
+   that could only be known by examining the function body.  As an example,
+   consider this situation:
+
+
+CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow',
+                             'green', 'blue', 'purple');
+
+CREATE TABLE my_colors (color rainbow, note text);
+
+CREATE FUNCTION get_color_note (rainbow) RETURNS text AS
+  'SELECT note FROM my_colors WHERE color = $1'
+  LANGUAGE SQL;
+
+
+   (See  for an explanation of SQL-language
+   functions.)  PostgreSQL will be aware that
+   the get_color_note function depends on the rainbow
+   type: dropping the type would force dropping the function, because its
+   argument type would no longer be defined.  But PostgreSQL
+   will not consider get_color_note to depend on
+   the my_colors table, and so will not drop the function if
+   the table is dropped.  While there are disadvantages to this approach,
+   there are also benefits.  The function is still valid in some sense if the
+   table is missing, though executing it would cause an error; creating a new
+   table of the same name would allow the function to work again.
+