Clarify SPLIT PARTITION bound requirements in docs

The documentation said that the bounds of new partitions should not
overlap and that their combined bounds should equal the bounds of the
split partition.  That is misleading when a new DEFAULT partition is
specified, because the explicit partitions may cover only part of the
split partition while the DEFAULT partition covers the rest.

Clarify that new non-DEFAULT partition bounds must not overlap with
other new or existing partitions and must be contained within the bounds
of the split partition.  Also state that the combined bounds must exactly
match the split partition only when no new DEFAULT partition is specified.

While here, improve nearby wording about hash-partitioned target tables
and splitting a DEFAULT partition with the same partition name.

Author: Chao Li <lic@highgo.com>
Reviewed-by: Alexander Korotkov <aekorotkov@gmail.com>
Discussion: https://postgr.es/m/C18878AB-DEB2-4A61-9995-A035DD644B81@gmail.com

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1f9a456fd336ab810ca15e67aca7eb0ae454f303..dec34337d1ac10fdae9f2f14d06c1dd24cb0b9be 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1293,7 +1293,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     <listitem>
      <para>
       This form splits a single partition of the target table into new
-      partitions. Hash-partitioned target table is not supported.
+      partitions.  Hash-partitioned target tables are not supported.
       Only a simple, non-partitioned partition can be split.
       If the split partition is the <literal>DEFAULT</literal> partition,
       one of the new partitions must be <literal>DEFAULT</literal>.
@@ -1303,18 +1303,23 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
 
      <para>
-      The bounds of new partitions should not overlap with those of new or
-      existing partitions (except <replaceable class="parameter">partition_name</replaceable>).
-      The combined bounds of new partitions <literal>
+      The bounds of new non-<literal>DEFAULT</literal> partitions must not
+      overlap with those of new or existing partitions, except
+      <replaceable class="parameter">partition_name</replaceable>, and must be
+      contained within the bounds of the split partition
+      <replaceable class="parameter">partition_name</replaceable>.
+      If no new <literal>DEFAULT</literal> partition is specified, the
+      combined bounds of the new partitions
+      <literal>
       <replaceable class="parameter">partition_name1</replaceable>,
       <replaceable class="parameter">partition_name2</replaceable>[, ...]
-      </literal> should be equal to the bounds of the split partition
+      </literal> must exactly match the bounds of the split partition
       <replaceable class="parameter">partition_name</replaceable>.
       One of the new partitions can have the same name as the split partition
-      <replaceable class="parameter">partition_name</replaceable>
-      (this is suitable in case of splitting the <literal>DEFAULT</literal>
-      partition: after the split, the <literal>DEFAULT</literal> partition
-      remains with the same name, but its partition bound changes).
+      <replaceable class="parameter">partition_name</replaceable>.
+      This is useful when splitting the <literal>DEFAULT</literal> partition,
+      so that after the split, the <literal>DEFAULT</literal> partition
+      keeps the same name but its partition bound changes.
      </para>
 
      <para>