From: Michael Paquier <michael@paquier.xyz>
Date: Mon, 11 Apr 2022 00:49:13 +0000 (+0900)
Subject: doc: Clarify behavior of query planner locking with REINDEX
X-Git-Tag: REL_15_BETA1~208
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8ac700acffc7b17d88414be47b8dff44fb1ea681;p=thirdparty%2Fpostgresql.git

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 e6b25ee670f..6a0eca8b9ac 100644
--- 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