doc: Clarify behavior of query planner locking with REINDEX

michaelpq · michaelpq · commit 8ac700acffc7 · 2022-04-11T09:49:13.000+09:00
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
@@ -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
