diff options
| author | Peter Eisentraut <peter@eisentraut.org> | 2025-05-01 08:56:43 +0200 |
|---|---|---|
| committer | Peter Eisentraut <peter@eisentraut.org> | 2025-05-01 08:57:48 +0200 |
| commit | 06c4f3ae804e6680ff03a09c1f89dfb1ca3d90e9 (patch) | |
| tree | 70da6a68883d849760bfd7e42df8291f835f2ecb /doc | |
| parent | 9d924dbb37103b647c72a5252ad20770b8bae3a1 (diff) | |
| download | postgresql-06c4f3ae804e6680ff03a09c1f89dfb1ca3d90e9.tar.gz postgresql-06c4f3ae804e6680ff03a09c1f89dfb1ca3d90e9.zip | |
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 <rob@xzilla.net>
Discussion: https://postgr.es/m/00e6eb5f5c793b8ef722252c7a519c9a@oss.nttdata.com
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/sgml/ref/alter_table.sgml | 23 |
1 files changed, 16 insertions, 7 deletions
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 <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> |