Update discussion of ALTER TABLE ADD COLUMN, per Michael Fuhr.

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 6d29859ed974d5289df60e97ad409c5e059f2a2b..3ae7d241e7bc17868e928747e1781d104911c522 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Data Definition
@@ -1279,23 +1279,22 @@ WHERE c.altitude > 500 and c.tableoid = p.oid;
 
 ALTER TABLE products ADD COLUMN description text;
 
-    The new column will initially be filled with null values in the
-    existing rows of the table.
+    The new column is initially filled with whatever default
+    value is given (null if you don't specify a DEFAULT clause).
    
 
    
-    You can also define a constraint on the column at the same time,
+    You can also define constraints on the column at the same time,
     using the usual syntax:
 
 ALTER TABLE products ADD COLUMN description text CHECK (description <> '');
 
-    A new column cannot have a not-null constraint since the column
-    initially has to contain null values.  But you can add a not-null
-    constraint later.  Also, you cannot define a default value on a
-    new column.  According to the SQL standard, this would have to
-    fill the new columns in the existing rows with the default value,
-    which is not implemented yet.  But you can adjust the column
-    default later on.
+    In fact all the options that can be applied to a column description
+    in CREATE TABLE can be used here.  Keep in mind however
+    that the default value must satisfy the given constraints, or the
+    ADD will fail.  Alternatively, you can add
+    constraints later (see below) after you've filled in the new column
+    correctly.
    
   
 
@@ -1390,12 +1389,17 @@ ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
 
 ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77;
 
+    Note that this doesn't affect any existing rows in the table, it
+    just changes the default for future INSERT commands.
+   
+
+   
     To remove any default value, use
 
 ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
 
-    This is equivalent to setting the default to null, at least in
-    PostgreSQL.  As a consequence, it is not an error
+    This is equivalent to setting the default to null.
+    As a consequence, it is not an error
     to drop a default where one hadn't been defined, because the
     default is implicitly the null value.