Date: Mon, 30 Nov 2020 18:52:55 -0300
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Michael Paquier <michael@paquier.xyz>
Cc: James Coleman <jtc331@gmail.com>,
	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: <20201130215255.GA4219@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="6c2NcOVqGQ03X4Wi"
Content-Disposition: inline
In-Reply-To: <20200930091010.GU1996@paquier.xyz>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


--6c2NcOVqGQ03X4Wi
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On 2020-Sep-30, Michael Paquier wrote:

> +  <para>
> +   <command>CREATE INDEX</command> (including the <literal>CONCURRENTLY</literal>
> +   option) commands are included when <command>VACUUM</command> calculates what
> +   dead tuples are safe to remove even on tables other than the one being indexed.
> +  </para>
> FWIW, this is true as well for REINDEX CONCURRENTLY because both use
> the same code paths for index builds and validation, with basically
> the same waiting phases.  But is CREATE INDEX the correct place for
> that?  Wouldn't it be better to tell about such things on the VACUUM
> doc?

Yeah, I think it might be more sensible to document this in
maintenance.sgml, as part of the paragraph that discusses removing
tuples "to save space".  But making it inline with the rest of the flow,
it seems to distract from higher-level considerations, so I suggest to
make it a footnote instead.

I'm not sure on the wording to use; what about this?


--6c2NcOVqGQ03X4Wi
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="v5-0001-Note-CIC-and-RC-in-vacuum-s-doc.patch"

From 6c9ad72e4e61dbf05f34146cb67706dd675a38f0 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 v5] Note CIC and RC in vacuum's doc

Per James Coleman
---
 doc/src/sgml/maintenance.sgml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 4d8ad754f8..d68d7f936e 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -159,7 +159,17 @@
     concurrency control (<acronym>MVCC</acronym>, see <xref linkend="mvcc"/>): the row version
     must not be deleted while it is still potentially visible to other
     transactions. But eventually, an outdated or deleted row version is no
-    longer of interest to any transaction. The space it occupies must then be
+    longer of interest to any transaction.
+    <footnote>
+     <para>
+      Note that <command>VACUUM</literal> needs to retain tuples that are
+      nominally visible to transactions running
+      <command>CREATE INDEX CONCURRENTLY</command> or
+      <command>REINDEX CONCURRENTLY</command>, even when run on tables
+      other than the tables being indexed.
+     </para>
+    </footnote>
+    The space it occupies must then be
     reclaimed for reuse by new rows, to avoid unbounded growth of disk
     space requirements. This is done by running <command>VACUUM</command>.
    </para>
-- 
2.20.1


--6c2NcOVqGQ03X4Wi--