diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 4847d663165..f0a8b8650c4 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -854,14 +854,18 @@ ALTER TABLE [ IF EXISTS ] name When a column is added with ADD COLUMN, all existing rows in the table are initialized with the column's default value (NULL if no DEFAULT clause is specified). + If there is no DEFAULT clause, this is merely a metadata + change and does not require any immediate update of the table's data; + the added NULL values are supplied on readout, instead. - Adding a column with a non-null default or changing the type of an - existing column will require the entire table and indexes to be rewritten. - As an exception, if the USING clause does not change the column + Adding a column with a DEFAULT clause 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 USING 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, + an unconstrained domain over the new type, a table rewrite is not needed; but any indexes on the affected columns must still be rebuilt. Adding or removing a system oid column also requires rewriting the entire table. Table and/or index rebuilds may take a significant amount of time