Fix incomplete definition of ALTER TABLE ADD/DROP CONSTRAINT syntax.

Add some verbiage about recent tweaks to behavior of ADD and DROP
COLUMN when there are descendant tables.

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 7326bbe01c1ebe491325ced124384df89aa2f64e..eea25682eb095146606786eade15590aeb9f6797 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1,5 +1,5 @@
 
 
@@ -38,9 +38,9 @@ ALTER TABLE [ ONLY ] table [ * ]
     class="PARAMETER">new_column
 ALTER TABLE table
     RENAME TO new_table
-ALTER TABLE table
-    ADD table_constraint_definition
-ALTER TABLE [ ONLY ] table 
+ALTER TABLE [ ONLY ] table [ * ]
+    ADD table_constraint
+ALTER TABLE [ ONLY ] table [ * ]
    DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ]
 ALTER TABLE table
    OWNER TO new_owner 
@@ -110,7 +110,7 @@ ALTER TABLE table
      
 
      
-       table_constraint_definition 
+       table_constraint 
       
        
    New table constraint for the table.
@@ -298,7 +298,7 @@ ALTER TABLE table
    
 
    
-    ADD table_constraint_definition
+    ADD table_constraint
     
      
       This form adds a new constraint to a table using the same syntax as
@@ -311,7 +311,7 @@ ALTER TABLE table
     DROP CONSTRAINT
     
      
-      This form drops constraints on a table (and its children).
+      This form drops constraints on a table.
       Currently, constraints on tables are not required to have unique
       names, so there may be more than one constraint matching the specified
       name.  All such constraints will be dropped.
@@ -376,6 +376,22 @@ VACUUM FULL table;
     
    
 
+   
+    If a table has any descendant tables, it is not permitted to ADD or
+    RENAME a column in the parent table without doing the same to the
+    descendants --- that is, ALTER TABLE ONLY will be rejected.  This
+    ensures that the descendants always have columns matching the parent.
+   
+
+   
+    A recursive DROP COLUMN operation will remove a descendant table's column
+    only if the descendant does not inherit that column from any other
+    parents and never had an independent definition of the column.
+    A nonrecursive DROP COLUMN (i.e., ALTER TABLE ONLY ... DROP COLUMN)
+    never removes any descendant columns, but instead marks them as
+    independently defined rather than inherited.
+   
+
    
     Changing any  part  of  the schema of a system
     catalog is not permitted.