Improve documentation about CREATE INDEX CONCURRENTLY.

Clarify the description of which transactions will block a CREATE INDEX
CONCURRENTLY command from proceeding, and mention that the index might
still not be usable after CREATE INDEX completes.  (This happens if the
index build detected broken HOT chains, so that pg_index.indcheckxmin gets
set, and there are open old transactions preventing the xmin horizon from
advancing past the index's initial creation.  I didn't want to explain what
broken HOT chains are, though, so I omitted an explanation of exactly when
old transactions prevent the index from being used.)

Per discussion with Chris Travers.  Back-patch to all supported branches,
since the same text appears in all of them.

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index ec4146f75150570a0da7e7cbdcab6c010defb2fe..7dee4055dbc0bbcc468891bc54d269c212aa0621 100644 (file)
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -426,7 +426,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
     When this option is used,
     <productname>PostgreSQL</> must perform two scans of the table, and in
     addition it must wait for all existing transactions that could potentially
-    use the index to terminate.  Thus
+    modify or use the index to terminate.  Thus
     this method requires more total work than a standard index build and takes
     significantly longer to complete.  However, since it allows normal
     operations to continue while the index is built, this method is useful for
@@ -437,12 +437,15 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
    <para>
     In a concurrent index build, the index is actually entered into
     the system catalogs in one transaction, then two table scans occur in
-    two more transactions.  Any transaction active when the second table
-    scan starts can block concurrent index creation until it completes,
-    even transactions that only reference the table after the second table
-    scan starts.   Concurrent index creation serially waits for each old
-    transaction to complete using the method outlined in section <xref
-    linkend="view-pg-locks">.
+    two more transactions.  Before each table scan, the index build must
+    wait for existing transactions that have modified the table to terminate.
+    After the second scan, the index build must wait for any transactions
+    that have a snapshot (see <xref linkend="mvcc">) predating the second
+    scan to terminate.  Then finally the index can be marked ready for use,
+    and the <command>CREATE INDEX</> command terminates.
+    Even then, however, the index may not be immediately usable for queries:
+    in the worst case, it cannot be used as long as transactions exist that
+    predate the start of the index build.
    </para>
 
    <para>