From a7207a24d40e887f08cb8ad11659ecb42e85dead Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Tue, 5 Nov 2019 10:17:55 +0900
Subject: [PATCH] Doc: Improve description around ALTER TABLE ATTACH PARTITION
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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.GB23808@telsasoft.com
Backpatch-through: 10
---
doc/src/sgml/ddl.sgml | 12 ++++++------
doc/src/sgml/ref/alter_table.sgml | 29 +++++++++++++++--------------
2 files changed, 21 insertions(+), 20 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index d7158c1b034..9d6ec2c7382 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3952,14 +3952,14 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
<para>
Before running the <command>ATTACH PARTITION</command> command, it is
recommended to create a <literal>CHECK</literal> 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
- <literal>ACCESS EXCLUSIVE</literal> lock on that partition
+ partition constraint. Without the <literal>CHECK</literal> constraint,
+ the table will be scanned to validate the partition constraint while
+ holding an <literal>ACCESS EXCLUSIVE</literal> lock on that partition
and a <literal>SHARE UPDATE EXCLUSIVE</literal> lock on the parent table.
- One may then drop the constraint after <command>ATTACH PARTITION</command>
- is finished, because it is no longer necessary.
+ It may be desired to drop the redundant <literal>CHECK</literal> constraint
+ after <command>ATTACH PARTITION</command> is finished.
</para>
<para>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index cb9b60415de..f86de7a4ac7 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -841,7 +841,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
or as a default partition by using <literal>DEFAULT</literal>.
For each index in the target table, a corresponding
one will be created in the attached table; or, if an equivalent
- index already exists, will be attached to the target table's index,
+ index already exists, it will be attached to the target table's index,
as if <command>ALTER INDEX ATTACH PARTITION</command> had been executed.
Note that if the existing table is a foreign table, it is currently not
allowed to attach the table as a partition of the target table if there
@@ -864,23 +864,24 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
already exist.
If any of the <literal>CHECK</literal> constraints of the table being
attached is marked <literal>NO INHERIT</literal>, the command will fail;
- such a constraint must be recreated without the <literal>NO INHERIT</literal>
- clause.
+ such constraints must be recreated without the
+ <literal>NO INHERIT</literal> clause.
</para>
<para>
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
- <literal>CHECK</literal> 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 <literal>NULL</literal> values. If attaching
- a list partition that will not accept <literal>NULL</literal> values,
- also add <literal>NOT NULL</literal> 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
+ <literal>CHECK</literal> constraint to the table that allows only
+ rows satisfying the desired partition constraint before running this
+ command. The <literal>CHECK</literal> 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
+ <literal>NULL</literal> values. If attaching a list partition that will
+ not accept <literal>NULL</literal> values, also add
+ <literal>NOT NULL</literal> constraint to the partition key column,
+ unless it's an expression.
</para>
<para>
--
GitLab