Date: Wed, 30 Jul 2025 12:21:08 -0500
From: Nathan Bossart <nathandbossart@gmail.com>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: =?iso-8859-1?Q?Fr=E9d=E9ric?= Yhuel <frederic.yhuel@dalibo.com>,
	Corey Huinker <corey.huinker@gmail.com>,
	Bruce Momjian <bruce@momjian.us>,
	John Naylor <johncnaylorls@gmail.com>,
	Masahiko Sawada <sawada.mshk@gmail.com>,
	Jeff Davis <pgsql@j-davis.com>,
	jian he <jian.universality@gmail.com>,
	Matthias van de Meent <boekewurm+postgres@gmail.com>,
	Tom Lane <tgl@sss.pgh.pa.us>, Magnus Hagander <magnus@hagander.net>,
	Stephen Frost <sfrost@snowman.net>,
	Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>,
	Peter Smith <smithpb2250@gmail.com>,
	PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>,
	"alvherre@alvh.no-ip.org" <alvherre@alvh.no-ip.org>
Subject: Re: vacuumdb changes for stats import/export
Message-ID: <aIpUhBLeWnZf_IBt@nathan>
References: <4b94ca16-7a6d-4581-b2aa-4ea79dbc082a@dalibo.com>
 <aITkuWC4Ww88GsFL@momjian.us>
 <CAKFQuwa2-oW__J7gAcVKgZnx658qBx9GknwL-wqX_0VvDc1EBQ@mail.gmail.com>
 <aIT9HMuQNIFfIlFH@momjian.us>
 <CADkLM=f9eYO_2f2LEf9a2zR_Zw9a4LtVAeqC_TdQEJdTuR-V+Q@mail.gmail.com>
 <8320fa2e-9200-46e2-b905-4a4d84707020@dalibo.com>
 <aIeNeo-zGgevViNc@nathan>
 <b527f417-b27c-43bb-8623-4c703fc0ad72@dalibo.com>
 <CAKFQuwYzgRbRBH6T+QZ=Cioy5rLB4mJDZUH2CjMebpFBDKuC_g@mail.gmail.com>
 <aIfFinYmZuCIp_qw@nathan>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="zby1MXPr4joEnNJh"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <aIfFinYmZuCIp_qw@nathan>
Archived-At: <https://www.postgresql.org/message-id/aIpUhBLeWnZf_IBt%40nathan>
Precedence: bulk


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

On Mon, Jul 28, 2025 at 01:46:34PM -0500, Nathan Bossart wrote:
> On Mon, Jul 28, 2025 at 09:22:29AM -0700, David G. Johnston wrote:
>> On Monday, July 28, 2025, Frédéric Yhuel <frederic.yhuel@dalibo.com> wrote:
>>> On 7/28/25 16:47, Nathan Bossart wrote:
>>>> Obviously, this wording isn't clear enough.  We might need to either
>>>> remove that sentence or add "When used in conjunction with
>>>> --analyze-in-stages..."
>>>
>>> I vote for the second option.
>>
>> Makes sense. 
> 
> It seems like there is some support for adding "When used in conjunction
> with --analyze in stages..." to the beginning of the sentence.  I'll give
> it another day or two for any further discussion before committing.

Here is what I have staged for commit.

-- 
nathan

--zby1MXPr4joEnNJh
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: attachment;
	filename=v1-0001-doc-Adjust-documentation-for-vacuumdb-missing-sta.patch
Content-Transfer-Encoding: 8bit

From 82117acd6132351c368ec2670c4ba7f481d69ff9 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 30 Jul 2025 12:13:30 -0500
Subject: [PATCH v1 1/1] doc: Adjust documentation for vacuumdb
 --missing-stats-only.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sentence in question gave readers the impression that vacuumdb
deletes existing statistics for a period of time while analyzing,
but it's actually meant to convey that --analyze-in-stages will
temporarily replace existing statistics with ones generated with
lower statistics targets.

Reported-by: Frédéric Yhuel <frederic.yhuel@dalibo.com>
Reviewed-by: Frédéric Yhuel <frederic.yhuel@dalibo.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Discussion: https://postgr.es/m/4b94ca16-7a6d-4581-b2aa-4ea79dbc082a%40dalibo.com
Backpatch-through: 18
---
 doc/src/sgml/ref/vacuumdb.sgml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index b0680a61814..c7d9dca17b8 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -282,9 +282,11 @@ PostgreSQL documentation
       <listitem>
        <para>
         Only analyze relations that are missing statistics for a column, index
-        expression, or extended statistics object.  This option prevents
-        <application>vacuumdb</application> from deleting existing statistics
-        so that the query optimizer's choices do not become transiently worse.
+        expression, or extended statistics object.  When used with
+        <option>--analyze-in-stages</option>, this option prevents
+        <application>vacuumdb</application> from temporarily replacing existing
+        statistics with ones generated with lower statistics targets, thus
+        avoiding transiently worse query optimizer choices.
        </para>
        <para>
         This option can only be used in conjunction with
-- 
2.39.5 (Apple Git-154)


--zby1MXPr4joEnNJh--