doc: Improve explanations when a table rewrite is needed

Further improvement for commit 11bd8318602.  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 
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
index a75e75d800d4af417fee08ee075d451d1f80630a..d63f3a621acc6e7765c1375caa7ffb46a5b32429 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1436,22 +1436,31 @@ WITH ( MODULUS numeric_literal, REM
 
    
     Adding a column with a volatile DEFAULT
-    (e.g., clock_timestamp()), a generated column
-    (e.g., GENERATED BY DEFAULT AS IDENTITY), 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., clock_timestamp()), 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.
+   
+
+   
+    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 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.  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 text to
     varchar (or vice versa) without rebuilding the indexes
-    because these data types sort identically.  Table and/or index
+    because these data types sort identically.
+   
+
+   
+    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.