v62-0001-doc-refactor-alter-table-merge-partitions-v62.no-cfbot

From 9851f5d28535907f6add8c02f25e513c620ddacf Mon Sep 17 00:00:00 2001
From: jian he <jian.universality@gmail.com>
Date: Wed, 15 Oct 2025 19:23:50 +0800
Subject: [PATCH v62 1/1] doc refactor alter table merge partitions v62

doc changes.

Discussion: https://postgr.es/m/c73a1746-0cd0-6bdd-6b23-3ae0b7c0c582%40postgrespro.ru
---
 doc/src/sgml/ref/alter_table.sgml | 77 ++++++++++++++++---------------
 1 file changed, 39 insertions(+), 38 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 30dd5ef8466..f8dc2a10209 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1166,32 +1166,34 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       This form merges several partitions of the target table into a new partition.
       Hash-partitioned target table is not supported.
+      Only simple, non-partitioned partitions can be merged.
+      The new partition (<replaceable class="parameter">partition_name</replaceable>)
+      can have the same name as one of the merged partitions
+      (<literal><replaceable class="parameter">partition_name1</replaceable>,
+      <replaceable class="parameter">partition_name2</replaceable> [, ...]</literal>).
+     </para>
+
+     <para>
       If the <literal>DEFAULT</literal> partition is not in the
-      list of partitions <replaceable class="parameter">partition_name1</replaceable>,
-      <replaceable class="parameter">partition_name2</replaceable> [, ...]:
+      list of merged partitions:
       <itemizedlist>
        <listitem>
         <para>
-         For range-partitioned tables, the ranges of the partitions
-         <replaceable class="parameter">partition_name1</replaceable>,
-         <replaceable class="parameter">partition_name2</replaceable>, [...]
-         must be adjacent in order to be merged. Otherwise, an error will be
-         raised. The resulting combined range will be the new partition bound
-         for the partition <replaceable class="parameter">partition_name</replaceable>.
+         For range-partitioned tables, the ranges of merged partitions
+         must be adjacent in order to be merged.
+         The partition bounds of merged partitions are combined to form the new partition bound for
+         <replaceable class="parameter">partition_name</replaceable>.
         </para>
        </listitem>
        <listitem>
         <para>
          For list-partitioned tables, the partition bounds of
-         <replaceable class="parameter">partition_name1</replaceable>,
-         <replaceable class="parameter">partition_name2</replaceable>, [...]
-         are combined to form the new partition bound for
+         merged partitions are combined to form the new partition bound for
          <replaceable class="parameter">partition_name</replaceable>.
         </para>
        </listitem>
       </itemizedlist>
-      If the <literal>DEFAULT</literal> partition is in the list of partitions <replaceable class="parameter">partition_name1</replaceable>,
-      <replaceable class="parameter">partition_name2</replaceable> [, ...]:
+      If the <literal>DEFAULT</literal> partition is in the list of merged partitions:
       <itemizedlist>
        <listitem>
         <para>
@@ -1201,42 +1203,41 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
        </listitem>
        <listitem>
         <para>
-         The partition bound specifications for all partitions-
-         <replaceable class="parameter">partition_name1</replaceable>,
-         <replaceable class="parameter">partition_name2</replaceable>, [...]
-         can be arbitrary.
+         The partition bound specifications for merged partitions can be arbitrary.
         </para>
        </listitem>
       </itemizedlist>
-      The new partition <replaceable class="parameter">partition_name</replaceable>
-      can have the same name as one of the merged partitions. Only simple,
-      non-partitioned partitions can be merged.
      </para>
      <para>
-      If merged partitions have different owners, an error will be generated.
-      The owner of the merged partitions will be the owner of the new partition.
-      It is the user's responsibility to setup <acronym>ACL</acronym> on the
+      All merged partitions must have the same owner.
+      The owner of merged partitions will be the owner of the new partition.
+      It is the user's responsibility to setup <acronym>ACL</acronym> on
       new partition.
      </para>
+
      <para>
-      The indexes and identity are created later, after moving the data
-      into the new partition.
-      Extended statistics aren't copied from the parent table, for consistency with
-      <command>CREATE TABLE PARTITION OF</command>.
-      The new partition will inherit the same table access method, persistence
-      type, and tablespace as the parent table.
+       <command>ALTER TABLE MERGE PARTITION</command> uses the partitioned table itself
+       as the template to construct the new partition.
+       The new partition will inherit the same table access method, persistence
+       type, and tablespace as the partitioned table.
+
+       Constraints, column defaults, column generation expressions, identity columns,
+       indexes, triggers are copied from the partitioned table to the new
+       partition.  But extended statistics, security policies etc won't copied from
+       the partitioned table.
+       Indexes and identity columns copied from the partitioned table will be
+       created afterward, once the data has been moved into the new partition.
      </para>
+
      <para>
-      When partitions are merged, any individual objects belonging to those
-      partitions, such as constraints or statistics, will be dropped. This occurs
-      because <command>ALTER TABLE MERGE PARTITIONS</command> uses the partitioned table itself as the
-      template to define these objects.
-     </para>
-     <para>
-      If merged partitions have some objects dependent on them, the command can
-      not be done (<literal>CASCADE</literal> is not used, and an error will
-      be returned).
+      When partitions are merged, any objects depend on this partition, such as
+      constraints, triggers, extended statistics etc will be dropped.
+      Eventually we will drop all the merged partitions (using <literal>RESTRICT</literal> mode) too,
+      therefore if any objects still dependent on it,
+      <command>ALTER TABLE MERGE PARTITION</command> would fail.
+      (see <xref linkend="ddl-depend"/>).
      </para>
+
      <note>
       <para>
        Merging partitions acquires an <literal>ACCESS EXCLUSIVE</literal> lock on
-- 
2.34.1