database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-05 23:56:58 +03:00
Code

doc: Improve explanations when a table rewrite is needed

Browse Source 
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
This commit is contained in:
Peter Eisentraut 2025-05-01 08:56:43 +02:00
parent 9d924dbb37
commit 06c4f3ae80
1 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/src/sgml/ref/alter_table.sgml
View File

@ -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>