Doc: Improve description around ALTER TABLE ATTACH PARTITION

This clarifies more how to use and how to take advantage of constraints
when attaching a new partition.

Author: Justin Pryzby
Reviewed-by: Amit Langote, Álvaro Herrera, Michael Paquier
Discussion: https://postgr.es/m/20191028001207[email protected]
Backpatch-through: 10

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index d7158c1b034b18e67635230456156fc64995b34d..9d6ec2c7382eabecf63573cca1d5854b8566b75c 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3952,14 +3952,14 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
     
      Before running the ATTACH PARTITION command, it is
      recommended to create a CHECK constraint on the table to
-     be attached describing the desired partition constraint.  That way,
+     be attached matching the desired partition constraint. That way,
      the system will be able to skip the scan to validate the implicit
-     partition constraint. Without such a constraint, the table will be
-     scanned to validate the partition constraint while holding an
-     ACCESS EXCLUSIVE lock on that partition
+     partition constraint. Without the CHECK constraint,
+     the table will be scanned to validate the partition constraint while
+     holding an ACCESS EXCLUSIVE lock on that partition
      and a SHARE UPDATE EXCLUSIVE lock on the parent table.
-     One may then drop the constraint after ATTACH PARTITION
-     is finished, because it is no longer necessary.
+     It may be desired to drop the redundant CHECK constraint
+     after ATTACH PARTITION is finished.
     
 
     

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index cb9b60415dec53acb99e0876324ee5b843782bdd..f86de7a4ac776584507c1ec72eb08ce73a3eac8e 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -841,7 +841,7 @@ WITH ( MODULUS numeric_literal, REM
       or as a default partition by using DEFAULT.
       For each index in the target table, a corresponding
       one will be created in the attached table; or, if an equivalent
-      index already exists, will be attached to the target table's index,
+      index already exists, it will be attached to the target table's index,
       as if ALTER INDEX ATTACH PARTITION had been executed.
       Note that if the existing table is a foreign table, it is currently not
       allowed to attach the table as a partition of the target table if there
@@ -864,23 +864,24 @@ WITH ( MODULUS numeric_literal, REM
       already exist.
       If any of the CHECK constraints of the table being
       attached is marked NO INHERIT, the command will fail;
-      such a constraint must be recreated without the NO INHERIT
-      clause.
+      such constraints must be recreated without the
+      NO INHERIT clause.
      
 
      
       If the new partition is a regular table, a full table scan is performed
-      to check that no existing row in the table violates the partition
-      constraint.  It is possible to avoid this scan by adding a valid
-      CHECK constraint to the table that would allow only
-      the rows satisfying the desired partition constraint before running this
-      command.  It will be determined using such a constraint that the table
-      need not be scanned to validate the partition constraint.  This does not
-      work, however, if any of the partition keys is an expression and the
-      partition does not accept NULL values.  If attaching
-      a list partition that will not accept NULL values,
-      also add NOT NULL constraint to the partition key
-      column, unless it's an expression.
+      to check that existing rows in the table do not violate the partition
+      constraint. It is possible to avoid this scan by adding a valid
+      CHECK constraint to the table that allows only
+      rows satisfying the desired partition constraint before running this
+      command. The CHECK constraint will be used to
+      determine that the table need not be scanned to validate the partition
+      constraint. This does not work, however, if any of the partition keys
+      is an expression and the partition does not accept
+      NULL values. If attaching a list partition that will
+      not accept NULL values, also add
+      NOT NULL constraint to the partition key column,
+      unless it's an expression.