diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 9301f0227d..b2bab81840 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1301,6 +1301,29 @@ ALTER TABLE products ADD COLUMN description text;
value is given (null if you don't specify a DEFAULT clause).
+
+
+ From PostgreSQL 11, adding a column with
+ a constant default value no longer means that each row of the table
+ needs to be updated when the ALTER TABLE 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 ALTER TABLE very fast even on large tables.
+
+
+
+ However, if the default value is volatile (e.g.
+ clock_timestamp())
+ each row will need to be updated with the value calculated at the time
+ ALTER TABLE is executed. To avoid a potentially
+ lengthy update operation, particularly if you intend to fill the column
+ with mostly nondefault values anyway, it may be preferable to add the
+ column with no default, insert the correct values using
+ UPDATE, and then add any desired default as described
+ below.
+
+
+
You can also define constraints on the column at the same time,
using the usual syntax:
@@ -1315,17 +1338,6 @@ ALTER TABLE products ADD COLUMN description text CHECK (description <> '')
correctly.
-
-
- Adding a column with a default requires updating each row of the
- table (to store the new column value). However, if no default is
- specified, PostgreSQL is able to avoid
- the physical update. So if you intend to fill the column with
- mostly nondefault values, it's best to add the column with no default,
- insert the correct values using UPDATE, and then add any
- desired default as described below.
-
-