From 94b79dc0f6412b1e73549c091d6561e0815d07d3 Mon Sep 17 00:00:00 2001
From: Masahiro Ikeda <ikedamsh@oss.nttdata.com>
Date: Tue, 3 Dec 2024 16:01:10 +0900
Subject: [PATCH v1] Doc: fix the rewrite condition when executing ALTER TABLE
 ADD COLUMN

Reported-by: Tatsuhito Kasahara
Author: Masahiro Ikeda
---
 doc/src/sgml/ddl.sgml             | 12 +-----------
 doc/src/sgml/ref/alter_table.sgml | 11 ++++++++---
 2 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index dea04d64db..489e4d8e71 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1623,17 +1623,7 @@ ALTER TABLE products ADD COLUMN description text;
 
    <tip>
     <para>
-     From <productname>PostgreSQL</productname> 11, adding a column with
-     a constant default value no longer means that each row of the table
-     needs to be updated when the <command>ALTER TABLE</command> statement
-     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 <command>ALTER TABLE</command> very fast even on large tables.
-    </para>
-
-    <para>
-     However, if the default value is volatile (e.g.,
-     <function>clock_timestamp()</function>)
+     If the default value is volatile (e.g., <function>clock_timestamp()</function>)
      each row will need to be updated with the value calculated at the time
      <command>ALTER TABLE</command> is executed. To avoid a potentially
      lengthy update operation, particularly if you intend to fill the column
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index c8f7ab7d95..ade4b6d3c8 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1399,12 +1399,17 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     non-volatile <literal>DEFAULT</literal> is specified, the default is
     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
-    rows.  If no <literal>DEFAULT</literal> is specified, NULL is used.  In
-    neither case is a rewrite of the table required.
+    rows, ensuring it will be returned the next time the row is accessed.
+    The value will be only applied when the table is rewritten, 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>
-    Adding a column with a volatile <literal>DEFAULT</literal> or
+    Adding a column with a volatile (e.g., <function>clock_timestamp()</function>)
+    <literal>DEFAULT</literal>, a generated column (e.g., <literal>GENERATED BY DEFAULT
+    AS IDENTITY</literal>), a domain data type with constraints, or
     changing the type of an existing column will require 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
-- 
2.34.1