diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 8616a8e9cc..6bc43ad10c 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -4283,18 +4283,20 @@ CREATE TABLE measurement_y2008m02 PARTITION OF measurement TABLESPACE fasttablespace; - As an alternative, it is sometimes more convenient to create the - new table outside the partition structure, and attach it as a - partition later. This allows new data to be loaded, checked, and - transformed prior to it appearing in the partitioned table. + As an alternative to creating a new partition, it is sometimes more + convenient to create a new table separate from the partition structure + and attach it as a partition later. This allows new data to be loaded, + checked, and transformed prior to it appearing in the partitioned table. Moreover, the ATTACH PARTITION operation requires - only SHARE UPDATE EXCLUSIVE lock on the - partitioned table, as opposed to the ACCESS - EXCLUSIVE lock that is required by CREATE TABLE - ... PARTITION OF, so it is more friendly to concurrent - operations on the partitioned table. - The CREATE TABLE ... LIKE option is helpful - to avoid tediously repeating the parent table's definition: + only a SHARE UPDATE EXCLUSIVE lock on the + partitioned table rather than the ACCESS EXCLUSIVE + lock required by CREATE TABLE ... PARTITION OF, + so it is more friendly to concurrent operations on the partitioned table; + see ALTER TABLE ... ATTACH PARTITION + for additional details. The + CREATE TABLE ... LIKE + option can be helpful to avoid tediously repeating the parent table's + definition; for example: CREATE TABLE measurement_y2008m02 @@ -4313,17 +4315,15 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02 - Before running the ATTACH PARTITION command, it is - recommended to create a CHECK constraint on the table to - be attached that matches the expected partition constraint, as - illustrated above. That way, the system will be able to skip the scan - which is otherwise needed to validate the implicit - partition constraint. Without the CHECK constraint, + Note that when running the ATTACH PARTITION command, the table will be scanned to validate the partition constraint while holding an ACCESS EXCLUSIVE lock on that partition. - It is recommended to drop the now-redundant CHECK - constraint after the ATTACH PARTITION is complete. If - the table being attached is itself a partitioned table, then each of its + As shown above, it is recommended to avoid this scan by creating a + CHECK constraint matching the expected partition + constraint on the table prior to attaching it. Once the + ATTACH PARTITION is complete, it is recommended to drop + the now-redundant CHECK constraint. + 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. @@ -4333,7 +4333,7 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02 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 + this is not done, 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 @@ -4344,21 +4344,21 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02 - As explained above, it is possible to create indexes on partitioned tables - so that they are applied automatically to the entire hierarchy. - This is very - convenient, as not only will the existing partitions become indexed, but - also any partitions that are created in the future will. One limitation is - that it's not possible to use the CONCURRENTLY - qualifier when creating such a partitioned index. To avoid long lock - times, it is possible to use CREATE INDEX ON ONLY - the partitioned table; such an index is marked invalid, and the partitions - do not get the index applied automatically. The indexes on partitions can - be created individually using CONCURRENTLY, and then - attached to the index on the parent using - ALTER INDEX .. ATTACH PARTITION. Once indexes for all - partitions are attached to the parent index, the parent index is marked - valid automatically. Example: + As mentioned earlier, it is possible to create indexes on partitioned + tables so that they are applied automatically to the entire hierarchy. + This can be very convenient as not only will all existing partitions be + indexed, but any future partitions will be as well. However, one + limitation when creating new indexes on partitioned tables is that it + is not possible to use the CONCURRENTLY + qualifier, which could lead to long lock times. To avoid this, you can + use CREATE INDEX ON ONLY the partitioned table, which + creates the new index marked as invalid, preventing automatic application + to existing partitions. Instead, indexes can then be created individually + on each partition using CONCURRENTLY and + attached to the partitioned index on the parent + using ALTER INDEX ... ATTACH PARTITION. Once indexes for + all the partitions are attached to the parent index, the parent index will + be marked valid automatically. Example: CREATE INDEX measurement_usls_idx ON ONLY measurement (unitsales);