Document piecemeal construction of partitioned indexes

Continuous operation cannot be achieved without applying this technique,
so it needs to be properly described.

Author: Álvaro Herrera
Reported-by: Tom Lane
Discussion: https://postgr.es/m/8756.1556302759@sss.pgh.pa.us

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 5fe5f864028b088ceafe75388c1ebc05633bcc09..cce1618fc135507cd5278cfe68ec5e00d5e325aa 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3948,6 +3948,44 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
      One may then drop the constraint after ATTACH PARTITION
      is finished, because it is no longer necessary.
     
+
+    
+     As explained above, it is possible to create indexes on partitioned tables
+     and they are applied automatically to the entire hierarchy.  This is very
+     convenient, as not only the existing partitions will 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 overcome 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 separately using CONCURRENTLY, and later
+     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:
+
+CREATE INDEX measurement_usls_idx ON ONLY measurement (unitsales);
+
+CREATE INDEX measurement_usls_200602_idx
+    ON measurement_y2006m02 (unitsales);
+ALTER INDEX measurement_usls_idx
+    ATTACH PARTITION measurement_usls_200602_idx;
+...
+
+
+     This technique can be used with UNIQUE and
+     PRIMARY KEY constraints too; the indexes are created
+     implicitly when the constraint is created.  Example:
+
+ALTER TABLE ONLY measurement ADD UNIQUE (city_id, logdate);
+
+ALTER TABLE measurement_y2006m02 ADD UNIQUE (city_id, logdate);
+ALTER INDEX measurement_city_id_logdate_key
+    ATTACH PARTITION measurement_y2006m02_city_id_logdate_key;
+...
+
+