Expand warnings on locks acquired by CREATE INDEX CONCURRENTLY

The previous wording wasn't explicit enough, which could misled readers
into thinking that the locks acquired are more restricted in nature than
they really are.  The resulting optimism can be damaging to morale when
confronted with reality, as has been observed in the field.

Greg Smith

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 03b99194909e515b3d3dc08b8a6ab424fe0fd2a2..5f23316c78dec402952a70e43cfe110cb01de08e 100644 (file)
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -368,7 +368,16 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
    <para>
     In a concurrent index build, the index is actually entered into the
     system catalogs in one transaction, then the two table scans occur in a
-    second and third transaction.
+    second and third transaction.  All active transactions at the time the
+    second table scan starts, not just ones that already involve the table,
+    have the potential to block the concurrent index creation until they
+    finish.  When checking for transactions that could still use the original
+    index, concurrent index creation advances through potentially interfering
+    older transactions one at a time, obtaining shared locks on their virtual
+    transaction identifiers to wait for them to complete.
+   </para>
+
+   <para>
     If a problem arises while scanning the table, such as a
     uniqueness violation in a unique index, the <command>CREATE INDEX</>
     command will fail but leave behind an <quote>invalid</> index. This index