From 4967ed4d0e1cff0c6e74c9b13369b88436ba217e Mon Sep 17 00:00:00 2001
From: jcoleman <jtc331@gmail.com>
Date: Tue, 29 Mar 2022 13:45:25 +0000
Subject: [PATCH v1] Restructure ALTER TABLE notes to clarify table rewrites
 and verification scans

The current set of notes includes several examples of when rewriting table
(and its indexes) or scanning a table to validate constraints is required
and when it can be avoided. However the structure makes this hard to
follow. Here we layout out rewriting and validating as two distinct
possibilities and list the cases where they happen. That also has the
benefit of moving some of the details about rewrites (e.g., time and
disk space requirements) out of the discussion for a specific operation.

Thanks to David G. Johnston for the initial inspiration for this
structuring.
---
 doc/src/sgml/ref/alter_table.sgml | 55 +++++++++++++++++++------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 5c0735e08a..b3af264ecc 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1351,36 +1351,49 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </para>
 
    <para>
-    When a column is added with <literal>ADD COLUMN</literal> and a
-    non-volatile <literal>DEFAULT</literal> is specified, the default is
-    evaluated at the time of the statement and the result stored in the
-    table's metadata.  That value will be used for the column for all existing
-    rows.  If no <literal>DEFAULT</literal> is specified, NULL is used.  In
-    neither case is a rewrite of the table required.
+    The following alterations of the table require the entire table, and in some 
+    cases its indexes as well, to be rewritten. For a large table such a rewrite
+    may take a significant amount of time and will temporarily require as much as
+    double the disk space.
    </para>
 
    <para>
-    Adding a column with a volatile <literal>DEFAULT</literal> 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
-    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; but any indexes on the affected columns must still be rebuilt.
-    Table and/or index rebuilds may take a
-    significant amount of time for a large table; and will temporarily require
-    as much as double the disk space.
+    Changing the type of an existing column will require the entire table and its
+    indexes to be rewritten. As an exception, if the <literal>USING</literal> 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.
    </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,
-    but does not require a table rewrite.
+    Adding a column with a volatile <literal>DEFAULT</literal> also requires the
+    entire table and its indexes to be rewritten. A non-volatile (or absent, in
+    which case <literal>NULL</literal> is used) <literal>DEFAULT</literal> is
+    evaluated at the time of the statement and the result is stored in the table's
+    metadata, thus avoiding the rewrite requirement.
    </para>
 
    <para>
-    Similarly, when attaching a new partition it may be scanned to verify that
-    existing rows meet the partition constraint.
+    The following alterations of the table require that it be scanned in its entirety
+    to ensure that no existing values are contrary to the new constraints placed on
+    the table. Constraints backed by indexes will scan the table as a side-effect of
+    populating the new index with data.
+   </para>
+
+   <para>
+    Adding either a CHECK constraint or a <literal>NOT NULL</literal> constraint on
+    an existing column requires scanning the table to verify that existing rows meet
+    the constraint.
+   </para>
+
+   <para>
+    Adding a foreign key constraint requires scanning the table to verify that all
+    existing values exist in the referenced table.
+   </para>
+
+   <para>
+    Attaching a new partition requires scanning the table to verify that existing
+    rows meet the partition constraint.
    </para>
 
    <para>
-- 
2.20.1

