Doc: Improve description around ALTER TABLE ATTACH PARTITION
authorMichael Paquier
Tue, 5 Nov 2019 01:18:05 +0000 (10:18 +0900)
committerMichael Paquier
Tue, 5 Nov 2019 01:18:05 +0000 (10:18 +0900)
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

doc/src/sgml/ddl.sgml
doc/src/sgml/ref/alter_table.sgml

index 12905c972113580f99b1b35743dee8a588e9df48..9235797af2dabb03e34292aa6f3e1ce189702867 100644 (file)
@@ -3308,13 +3308,13 @@ 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 the parent table.
-     One may then drop the constraint after ATTACH PARTITION
-     is finished, because it is no longer necessary.
+     partition constraint. Without the CHECK constraint,
+     the table will be scanned to validate the partition constraint while
+     holding an ACCESS EXCLUSIVE lock on the parent table.
+     It may be desired to drop the redundant CHECK constraint
+     after ATTACH PARTITION is finished.
     
    
 
index dae63077eedf69e2ed2723e25f11da231e5e9401..30644170ca5ed8b0a9af34132fcdaebc5492c0eb 100644 (file)
@@ -781,23 +781,24 @@ ALTER TABLE [ IF EXISTS ] name
       FOREIGN KEY constraints are not considered.
       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.