v0002-Justin-doc_mention_CREATE+ATTACH_PARTITION.patch

commit 723fa7df82f39aed5d58e5e52ba80caa8cb13515
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date:   Mon Jul 18 09:24:55 2022 -0500


    doc: mention CREATE+ATTACH PARTITION as an alternative to CREATE TABLE..PARTITION OF
    
    In v12, 898e5e329 (Allow ATTACH PARTITION with only ShareUpdateExclusiveLock)
    allows attaching a partition with a weaker lock than in CREATE..PARTITION OF,
    but it does that silently.  On the one hand, things that are automatically
    better, without having to enable the option are the best kind of feature.
    
    OTOH, I doubt many people know to do that, because the docs don't say
    so, because it was implemented as an transparent improvement.  This
    patch adds a bit of documentations to make that more visible.
    
    See also: 898e5e3290a72d288923260143930fb32036c00c
    Should backpatch to v12


diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 360284e37d6..66138b9299d 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -4092,7 +4092,9 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
 
     <para>
      The <command>ATTACH PARTITION</command> command requires taking a
-     <literal>SHARE UPDATE EXCLUSIVE</literal> lock on the partitioned table.
+     <literal>SHARE UPDATE EXCLUSIVE</literal> lock on the partitioned table,
+     as opposed to the <literal>Access Exclusive</literal> lock which is
+     required by <literal>CREATE TABLE .. PARTITION OF</literal>.
     </para>
 
     <para>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index c14b2010d81..54dbfa72e4c 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -619,6 +619,16 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       with <literal>DROP TABLE</literal> requires taking an <literal>ACCESS
       EXCLUSIVE</literal> lock on the parent table.
      </para>
+
+     <para>
+      Note that creating a partition using <literal>PARTITION OF</literal>
+      requires taking an <literal>ACCESS EXCLUSIVE</literal> lock on the parent
+      table.  It may be preferable to first create a separate table and then
+      attach it, which does not require as strong a lock.
+      See <link linkend="sql-altertable-attach-partition">ATTACH PARTITION</link>
+      for more information.
+     </para>
+
     </listitem>
    </varlistentry>