Avoid promising that "ADD COLUMN ... DEFAULT NULL" is free.

The system realizes that DEFAULT NULL is dummy in simple cases, but not if
a cast function (such as a length coercion) needs to be applied.  It's
dubious that suppressing that function call would be appropriate, anyway.
For the moment, let's just adjust the docs to say that you should omit the
DEFAULT clause if you don't want a rewrite to happen.  Per gripe from Amit
Langote.

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 4847d6631654aa8595c36ccacb787ba39cb5c45c..f0a8b8650c4dbc96ee7cf4b25bdc975784ec4840 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -854,14 +854,18 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
     When a column is added with <literal>ADD COLUMN</literal>, all existing
     rows in the table are initialized with the column's default value
     (NULL if no <literal>DEFAULT</> clause is specified).
+    If there is no <literal>DEFAULT</> clause, this is merely a metadata
+    change and does not require any immediate update of the table's data;
+    the added NULL values are supplied on readout, instead.
    </para>
 
    <para>
-    Adding a column with a non-null default or changing the type of an
-    existing column will require the entire table and indexes to be rewritten.
-    As an exception, if the <literal>USING</> clause does not change the column
+    Adding a column with a <literal>DEFAULT</> clause or changing the type of
+    an existing column will require the entire table and its indexes to be
+    rewritten.  As an exception when changing the type of an existing column,
+    if the <literal>USING</> clause does not change the column
     contents and the old type is either binary coercible to the new type or
-    an unconstrained domain over the new type, a table rewrite is not needed,
+    an unconstrained domain over the new type, a table rewrite is not needed;
     but any indexes on the affected columns must still be rebuilt.  Adding or
     removing a system <literal>oid</> column also requires rewriting the entire
     table.  Table and/or index rebuilds may take a significant amount of time