Doc: Clarify lock levels taken during ATTACH PARTITION

It wasn't all that clear which lock levels, if any, would be held on the
DEFAULT partition during an ATTACH PARTITION operation.

Also, clarify which locks will be taken if the DEFAULT partition or the
table being attached are themselves partitioned tables.

Here I'm only backpatching to v12 as before then we obtained an ACCESS
EXCLUSIVE lock on the partitioned table.  It seems much less relevant to
mention which locks are taken on other tables when the partitioned table
itself is locked with an ACCESS EXCLUSIVE lock.

Author: Matthias van de Meent, David Rowley
Discussion: https://postgr.es/m/CAEze2WiTB6iwrV8W_J=fnrnZ7fowW3qu-8iQ8zCHP3FiQ6+o-A@mail.gmail.com
Backpatch-through: 12

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 605027e853529b2d1f536052449891fd7e2e0199..dc978fbd7b350ddb8c5fb00c4d91327c4c0f8114 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3968,6 +3968,11 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
 
     
 
+    
+     The ATTACH PARTITION command requires taking a
+     SHARE UPDATE EXCLUSIVE lock on the partitioned table.
+    
+
     
      Before running the ATTACH PARTITION command, it is
      recommended to create a CHECK constraint on the table to
@@ -3976,10 +3981,27 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
      which is otherwise needed to validate the implicit
      partition constraint. Without the CHECK constraint,
      the table will be scanned to validate the partition constraint while
-     holding both an ACCESS EXCLUSIVE lock on that partition
-     and a SHARE UPDATE EXCLUSIVE lock on the parent table.
+     holding an ACCESS EXCLUSIVE lock on that partition.
      It is recommended to drop the now-redundant CHECK
-     constraint after ATTACH PARTITION is finished.
+     constraint after the ATTACH PARTITION is complete.  If
+     the table being attached is itself a partitioned table then each of its
+     sub-partitions will be recursively locked and scanned until either a
+     suitable CHECK constraint is encountered or the leaf
+     partitions are reached.
+    
+
+    
+     Similarly, if the partitioned table has a DEFAULT
+     partition, it is recommended to create a CHECK
+     constraint which excludes the to-be-attached partition's constraint.  If
+     this is not done then the DEFAULT partition will be
+     scanned to verify that it contains no records which should be located in
+     the partition being attached.  This operation will be performed whilst
+     holding an ACCESS EXCLUSIVE lock on the 
+     DEFAULT partition.  If the DEFAULT partition
+     is itself a partitioned table then each of its partitions will be
+     recursively checked in the same way as the table being attached, as
+     mentioned above.
     
 
     

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 68ef3e9b4f363e15faa2226c847a78c1968307df..beae516f3d116a9ea07ea1241bbd7a69897b56ce 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -934,8 +934,17 @@ WITH ( MODULUS numeric_literal, REM
      
       Attaching a partition acquires a
       SHARE UPDATE EXCLUSIVE lock on the parent table,
-      in addition to ACCESS EXCLUSIVE locks on the table
-      to be attached and on the default partition (if any).
+      in addition to the ACCESS EXCLUSIVE locks on the table
+      being attached and on the default partition (if any).
+     
+
+     
+      Further locks must also be held on all sub-partitions if the table being
+      attached is itself a partitioned table.  Likewise if the default
+      partition is itself a partitioned table.  The locking of the
+      sub-partitions can be avoided by adding a CHECK
+      constraint as described in
+      .