diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index a75e75d800d..d63f3a621ac 100644
--- 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.