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> <para>
Adding a column with a volatile <literal>DEFAULT</literal> Adding a column with a volatile <literal>DEFAULT</literal>
(e.g., <function>clock_timestamp()</function>), a generated column (e.g., <function>clock_timestamp()</function>), a stored generated column,
(e.g., <literal>GENERATED BY DEFAULT AS IDENTITY</literal>), a domain an identity column, or a column with a domain data type that has
data type with constraints will require the entire table and its constraints will cause the entire table and its indexes to be rewritten.
indexes to be rewritten, as will changing the type of an existing Adding a virtual generated column never requires a rewrite.
column. As an exception, when changing the type of an existing column, </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 if the <literal>USING</literal> clause does not change the column
contents and the old type is either binary coercible to the new type 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 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 can verify that the new index would be logically equivalent to the
existing one. For example, if the collation for a column has been existing one. For example, if the collation for a column has been
changed, an index rebuild is required because the new sort changed, an index rebuild is required because the new sort
order might be different. However, in the absence of a collation order might be different. However, in the absence of a collation
change, a column can be changed from <type>text</type> to change, a column can be changed from <type>text</type> to
<type>varchar</type> (or vice versa) without rebuilding the indexes <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, rebuilds may take a significant amount of time for a large table,
and will temporarily require as much as double the disk space. and will temporarily require as much as double the disk space.
</para> </para>