database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-29 10:41:53 +03:00
Code Activity

doc: Explain more thoroughly when a table rewrite is needed

Browse Source 
Author: Masahiro Ikeda <ikedamsh@oss.nttdata.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/00e6eb5f5c793b8ef722252c7a519c9a@oss.nttdata.com
This commit is contained in:
Álvaro Herrera
2025-03-14 20:44:59 +01:00
parent 1c9242b2cd
commit 11bd831860
2 changed files with 29 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/sgml/ddl.sgml
View File

@ -1650,17 +1650,15 @@ ALTER TABLE products ADD COLUMN description text;
<tip> <tip>
<para> <para>
From <productname>PostgreSQL</productname> 11, adding a column with Adding a column with a constant default value does not require each row of
a constant default value no longer means that each row of the table the table to be updated when the <command>ALTER TABLE</command> statement
needs to be updated when the <command>ALTER TABLE</command> statement
is executed. Instead, the default value will be returned the next time is executed. Instead, the default value will be returned the next time
the row is accessed, and applied when the table is rewritten, making the row is accessed, and applied when the table is rewritten, making
the <command>ALTER TABLE</command> very fast even on large tables. the <command>ALTER TABLE</command> very fast even on large tables.
</para> </para>
<para> <para>
However, if the default value is volatile (e.g., If the default value is volatile (e.g., <function>clock_timestamp()</function>)
<function>clock_timestamp()</function>)
each row will need to be updated with the value calculated at the time each row will need to be updated with the value calculated at the time
<command>ALTER TABLE</command> is executed. To avoid a potentially <command>ALTER TABLE</command> is executed. To avoid a potentially
lengthy update operation, particularly if you intend to fill the column lengthy update operation, particularly if you intend to fill the column

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

@ -1421,30 +1421,36 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para> <para>
When a column is added with <literal>ADD COLUMN</literal> and a When a column is added with <literal>ADD COLUMN</literal> and a
non-volatile <literal>DEFAULT</literal> is specified, the default is non-volatile <literal>DEFAULT</literal> is specified, the default value is
evaluated at the time of the statement and the result stored in the evaluated at the time of the statement and the result stored in the
table's metadata. That value will be used for the column for all existing table's metadata, where it will be returned when any existing rows are
rows. If no <literal>DEFAULT</literal> is specified, NULL is used. In accessed. The value will be only applied when the table is rewritten,
neither case is a rewrite of the table required. making the <command>ALTER TABLE</command> very fast even on large tables.
If no column constraints are specified, NULL is used as the
<literal>DEFAULT</literal>. In neither case is a rewrite of the table
required.
</para> </para>
<para> <para>
Adding a column with a volatile <literal>DEFAULT</literal> or Adding a column with a volatile <literal>DEFAULT</literal>
changing the type of an existing column will require the entire table and (e.g., <function>clock_timestamp()</function>), a generated column
its indexes to be rewritten. As an exception, when changing the type of an (e.g., <literal>GENERATED BY DEFAULT AS IDENTITY</literal>), a domain
existing column, if the <literal>USING</literal> clause does not change data type with constraints will require the entire table and its
the column contents and the old type is either binary coercible to the new indexes to be rewritten, as will changing the type of an existing
type or an unconstrained domain over the new type, a table rewrite is not column. As an exception, when changing the type of an existing column,
needed. However, indexes must always be rebuilt unless the system can if the <literal>USING</literal> clause does not change the column
verify that the new index would be logically equivalent to the existing contents and the old type is either binary coercible to the new type
one. For example, if the collation for a column has been changed, an index or an unconstrained domain over the new type, a table rewrite is not
rebuild is always required because the new sort order might be different. needed. However, indexes must always be rebuilt unless the system
However, in the absence of a collation change, a column can be changed can verify that the new index would be logically equivalent to the
from <type>text</type> to <type>varchar</type> (or vice versa) without existing one. For example, if the collation for a column has been
rebuilding the indexes because these data types sort identically. changed, an index rebuild is required because the new sort
Table and/or index rebuilds may take a order might be different. However, in the absence of a collation
significant amount of time for a large table; and will temporarily require change, a column can be changed from <type>text</type> to
as much as double the disk space. <type>varchar</type> (or vice versa) without rebuilding the indexes
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.
</para> </para>
<para> <para>