Date: Tue, 12 Jan 2021 16:51:39 -0300
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: James Coleman <jtc331@gmail.com>
Cc: Michael Paquier <michael@paquier.xyz>,
	David Johnston <david.g.johnston@gmail.com>,
	PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>,
	Andres Freund <andres@anarazel.de>
Subject: Re: [DOC] Document concurrent index builds waiting on each other
Message-ID: <20210112195139.GA31932@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="+QahgC5+KEYLbs62"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAAaqYe8SYavGdG1yKRvBEv9JV5Ls7FdFj7y6pE93+iqdj6FnHQ@mail.gmail.com>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


--+QahgC5+KEYLbs62
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On 2020-Dec-01, James Coleman wrote:

> On Tue, Dec 1, 2020 at 6:51 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> > Makes sense.  ISTM that if we want to have a cautionary blurb CIC docs,
> > it should go in REINDEX CONCURRENTLY as well.
> 
> Agreed. Or, alternatively, a blurb something like "Please note how CIC
> interacts with VACUUM <link>...", and then the primary language in
> maintenance.sgml. That would have the benefit of maintaining the core
> language in only one place.

I looked into this again, and I didn't like what I had added to
maintenance.sgml at all.  It seems out of place where I put it; and I
couldn't find any great spots.  Going back to your original proposal,
what about something like this?  It's just one more para in the "notes"
section in CREATE INDEX and REINDEX pages, without any additions to the
VACUUM pages.

-- 
Álvaro Herrera                            39°49'30"S 73°17'W

--+QahgC5+KEYLbs62
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="v6-0001-Highlight-vacuum-consideration-in-create-index-do.patch"

From 8b0aa591f5d3f34ccdc2cd0fc6031dd421f229c2 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Mon, 30 Nov 2020 18:50:06 -0300
Subject: [PATCH v6] Highlight vacuum consideration in create index docs

Per James Coleman
---
 doc/src/sgml/ref/create_index.sgml | 5 +++++
 doc/src/sgml/ref/reindex.sgml      | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 2054d5d943..d951f14b09 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -829,6 +829,11 @@ Indexes:
    to remove an index.
   </para>
 
+  <para>
+   Like any long-running transaction, <command>CREATE INDEX</command> can
+   affect which tuples can be removed by concurrent <command>VACUUM</command>.
+  </para>
+
   <para>
    Prior releases of <productname>PostgreSQL</productname> also had an
    R-tree index method.  This method has been removed because
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 6e1cf06713..ef553f6481 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -436,6 +436,11 @@ Indexes:
     CONCURRENTLY</command> cannot.
    </para>
 
+   <para>
+    Like any long-running transaction, <command>REINDEX</command> can
+    affect which tuples can be removed by concurrent <command>VACUUM</command>.
+   </para>
+
    <para>
     <command>REINDEX SYSTEM</command> does not support
     <command>CONCURRENTLY</command> since system catalogs cannot be reindexed
-- 
2.20.1


--+QahgC5+KEYLbs62--