diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 7326bbe01c..eea25682eb 100644
--- 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.