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.yh...@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
>From 82117acd6132351c368ec2670c4ba7f481d69ff9 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nat...@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.yh...@dalibo.com>
Reviewed-by: Frédéric Yhuel <frederic.yh...@dalibo.com>
Reviewed-by: "David G. Johnston" <david.g.johns...@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)

Reply via email to