projects / postgresql.git / commitdiff
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 9d924db)
doc: Improve explanations when a table rewrite is needed
authorPeter Eisentraut <peter@eisentraut.org>
Thu, 1 May 2025 06:56:43 +0000 (08:56 +0200)
committerPeter Eisentraut <peter@eisentraut.org>
Thu, 1 May 2025 06:57:48 +0000 (08:57 +0200)
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 <rob@xzilla.net>
Discussion: https://postgr.es/m/00e6eb5f5c793b8ef722252c7a519c9a@oss.nttdata.com

doc/src/sgml/ref/alter_table.sgml patch | blob | blame | history

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 <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>
This is the main PostgreSQL git repository.