doc: Improve explanations when a table rewrite is needed

petere · petere · commit 06c4f3ae804e · 2025-05-01T08:57:48.000+02:00
Further improvement for commit 11bd831. That commit confused identity and generated columns; fix that. Also, virtual generated columns have since been added; add more details about that. Also some small rewordings and reformattings to further improve clarity. Reviewed-by: Robert Treat <rob@xzilla.net> Discussion: https://postgr.es/m/00e6eb5f5c793b8ef722252c7a519c9a@oss.nttdata.com
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
@@ -1436,22 +1436,31 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
    <para>
     Adding a column with a volatile <literal>DEFAULT</literal>
-    (e.g., <function>clock_timestamp()</function>), a generated column
-    (e.g., <literal>GENERATED BY DEFAULT AS IDENTITY</literal>), a domain
-    data type with constraints will require the entire table and its
-    indexes to be rewritten, as will changing the type of an existing
-    column.  As an exception, when changing the type of an existing column,
+    (e.g., <function>clock_timestamp()</function>), a stored generated column,
+    an identity column, or a column with a domain data type that has
+    constraints will cause the entire table and its indexes to be rewritten.
+    Adding a virtual generated column never requires a rewrite.
+   </para>
+
+   <para>
+    Changing the type of an existing column will normally cause 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.  However, indexes must always be rebuilt unless the system
+    needed.  However, indexes will still be rebuilt unless the system
     can verify that the new index would be logically equivalent to the
     existing one.  For example, if the collation for a column has been
     changed, an index rebuild is required because the new sort
     order might be different.  However, in the absence of a collation
     change, a column can be changed from <type>text</type> to
     <type>varchar</type> (or vice versa) without rebuilding the indexes
-    because these data types sort identically.  Table and/or index
+    because these data types sort identically.
+   </para>
+
+   <para>
+    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.
    </para>
