From b1019154c749991a3e23cd8e5f82b31acbbdddc9 Mon Sep 17 00:00:00 2001
From: jcoleman <jtc331@gmail.com>
Date: Fri, 21 Jan 2022 18:50:39 +0000
Subject: [PATCH v4 2/2] Don't double document ADD COLUMN optimization details

Instead point people to the source of truth. This also avoids using
different language ("constant" versus "non-volatile").
---
 doc/src/sgml/ddl.sgml             | 22 ++++------------------
 doc/src/sgml/ref/alter_table.sgml | 11 ++++++++++-
 2 files changed, 14 insertions(+), 19 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 22f6c5c7ab..0ec1b7cd39 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1406,24 +1406,10 @@ ALTER TABLE products ADD COLUMN description text;
 
    <tip>
     <para>
-     From <productname>PostgreSQL</productname> 11, adding a column with
-     a constant default value no longer means that each row of the table
-     needs to be updated when the <command>ALTER TABLE</command> statement
-     is executed. Instead, the default value will be returned the next time
-     the row is accessed, and applied when the table is rewritten, making
-     the <command>ALTER TABLE</command> very fast even on large tables.
-    </para>
-
-    <para>
-     However, if the default value is volatile (e.g.,
-     <function>clock_timestamp()</function>)
-     each row will need to be updated with the value calculated at the time
-     <command>ALTER TABLE</command> is executed. To avoid a potentially
-     lengthy update operation, particularly if you intend to fill the column
-     with mostly nondefault values anyway, it may be preferable to add the
-     column with no default, insert the correct values using
-     <command>UPDATE</command>, and then add any desired default as described
-     below.
+     Adding a new column can require rewriting the whole table,
+     making it slow for large tables.  However, the rewrite can be optimized
+     away in some cases, depending on what default value is given to the
+     column.  See Notes on <xref linkend="sql-altertable"/> for details.
     </para>
    </tip>
 
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1dde16fa39..9d1f6f1130 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1361,7 +1361,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </para>
 
    <para>
-    Adding a column with a volatile <literal>DEFAULT</literal> or
+    Adding a column with a volatile <literal>DEFAULT</literal> (e.g.,
+    <function>clock_timestamp()</function>) 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</literal> clause does not change
@@ -1373,6 +1374,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     as much as double the disk space.
    </para>
 
+   <para>
+    When adding a column with a default requires a rewrite it may be preferable
+    to add the column with no default, insert the correct values using
+    <command>UPDATE</command>, and then add any desired default as described
+    below.  This is particularly true if you intend to fill the column
+    with mostly nondefault values anyway.
+   </para>
+
    <para>
     Adding a <literal>CHECK</literal> or <literal>NOT NULL</literal> constraint requires
     scanning the table to verify that existing rows meet the constraint,
-- 
2.17.1