doc: Clarify behavior of query planner locking with REINDEX

The documentation of REINDEX has never mentioned that the query planner
may take an ACCESS SHARE lock on the indexes depending on the query
used.  This adds also a note about prepared queries not impacted when
they do not use the index(es) rebuilt.

Author: Frédéric Yhuel
Reviewed-by: Guillaume Lelarge, Justin Pryzby
Discussion: https://postgr.es/m/65d08718-6f11-978a-4b5a-72b807d4c663@dalibo.com

diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index e6b25ee670f7376560b701eabe10e96352f439a1..6a0eca8b9acc92f38fc1cfe96ddbf4f12d61d1f1 100644 (file)
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -275,7 +275,12 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN
    considerations are rather different.  <command>REINDEX</command> locks out writes
    but not reads of the index's parent table.  It also takes an
    <literal>ACCESS EXCLUSIVE</literal> lock on the specific index being processed,
-   which will block reads that attempt to use that index.  In contrast,
+   which will block reads that attempt to use that index. In particular,
+   the query planner tries to take an <literal>ACCESS SHARE</literal>
+   lock on every index of the table, regardless of the query, and so
+   <command>REINDEX</command> blocks virtually any queries except for some
+   prepared queries whose plan has been cached and which don't use this very
+   index. In contrast,
    <command>DROP INDEX</command> momentarily takes an
    <literal>ACCESS EXCLUSIVE</literal> lock on the parent table, blocking both
    writes and reads.  The subsequent <command>CREATE INDEX</command> locks out