From 6ce8236ff40c8b5aeea93d2a155be1ef3210b8c4 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 16 Feb 2016 13:43:03 -0500 Subject: [PATCH] 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. --- doc/src/sgml/ref/create_index.sgml | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index ce36a1ba48..745089993b 100644 --- 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 ] 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 ] 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 . + 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 ) predating the second + scan to terminate. Then finally the index can be marked ready for use, + and the 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.