public inbox for pgsql-docs@postgresql.org  

help / color / mirror / Atom feed

From: Yushu Chen <gentcys@gmail.com>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: maciek@sakrejda.org
Cc: Shinya Kato <shinya11.kato@gmail.com>
Cc: Fujii Masao <masao.fujii@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: doc: Clarify ANALYZE VERBOSE output
Date: Wed, 15 Apr 2026 17:45:41 +0800
Message-ID: <CAP5x3paeoLBgL0jYU-WBcBv0pTKL0nehNZAohCBPdwCmMu6YEg@mail.gmail.com> (raw)
In-Reply-To: <CAKFQuwYHBDNe0nyASfUCaw+s1rO+=yKTBd24yUf6nF6a1gRALw@mail.gmail.com>
References: <CAOzEurTpMTUEW8kHu-zKB0EBtuPfpvyoJ--8pxKe87p24BGrpg@mail.gmail.com>
	<CAOtHd0AY4LuM+-JqFyzs4mPHG8yeAwfP5yr2EZg21RVO0442BA@mail.gmail.com>
	<CAHGQGwE2dC5aNBgV5AtpMMdZNpkGn1PAa9o=whi8_Wb3m3ruAA@mail.gmail.com>
	<CAKFQuwZUSetJvoXewwofTNP5dLfhg7S31NNJhZ=G+ZbOOCZ=ug@mail.gmail.com>
	<CAOzEurS7aNO=TnZztwnxJdLgmNnmotwcocxVR2s4qLrZ66ZkxQ@mail.gmail.com>
	<CAOtHd0AC7Yg-Fz+1uRHc=mqsVtpH6b5NM-uL_Chd2vwKT5jf7g@mail.gmail.com>
	<CAKFQuwYHBDNe0nyASfUCaw+s1rO+=yKTBd24yUf6nF6a1gRALw@mail.gmail.com>

Hi,

The discussion makes sense to me.

Just to add one variant for consideration:

"Emits detailed information about vacuum activity for each table in the
form of INFO and DETAIL messages."

Thanks.

On Tue, Apr 14, 2026 at 6:29 AM David G. Johnston <
david.g.johnston@gmail.com> wrote:

> On Mon, Apr 13, 2026 at 2:28 PM Maciek Sakrejda <m.sakrejda@gmail.com>
> wrote:
>
>> On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11.kato@gmail.com>
>> wrote:
>> > On Mon, Apr 6, 2026, 14:17 David G. Johnston <
>> david.g.johnston@gmail.com> wrote:
>> >>
>> >> How about something like:
>> >> “Enables sending an INFO message to the client (and server log) as
>> each table is processed.  This message contains: etc…”
>> >>
>> >> And then let’s tell the user what info they are getting and what it
>> means (where necessary).
>> >>
>> >> I concur being specific about when these messages arrive, and IMO
>> where, should be specified.  But losing the detail of “report” is not good;
>> but not sure why we are being vague so suggest we just go all-in on
>> specificity.
>> >
>> > Thank you for the suggestion. I'd prefer to keep this patch focused;
>> since the verbose output of both commands is subject to change, listing
>> every individual field in the documentation would require frequent updates.
>> >
>> > I believe the current "Outputs" section is intentionally kept simple to
>> minimize maintenance overhead. While expanding it might be a worthwhile
>> follow-up, it probably deserves its own dedicated discussion.
>>
>> +1, listing output details is signing up for busywork.
>
>
> Given how expansive and thorough our documentation is, and the fact this
> is user-facing output, I'm not seeing why this gets a pass on the
> documentation requirement.  That said, I concur this patch needn't be
> responsible for dealing with that - I'm not even sure whether trying to do
> that on the vacuum/analyze pages is even the correct choice since at least
> some of what is output is object-specific and not generic to vacuum
> itself.  Though stuff like timings are.  Even if we want to leave ourselves
> the "it's undocumented so it can be changed at will" clause we can simply
> write that in.
>
> maybe something
>> along these lines:
>>
>> "Prints detailed stats at <literal>INFO</literal> level for each table
>> as it is processed."
>>
>>
> I really don't like the word "Print" here.  What the client decides to do
> with the INFO message is up to them - the interface to document for the
> server is simply sending the message and its details.
>
> I was apparently mistaken about this info showing in the server log file
> though.
>
> So that leaves me with suggesting:
>
> "Enables the sending of a detailed INFO message to the client after each
> table is processed."
>
> David J.
>
>

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-docs@postgresql.org
  Cc: gentcys@gmail.com, david.g.johnston@gmail.com, maciek@sakrejda.org, shinya11.kato@gmail.com, masao.fujii@gmail.com, pgsql-docs@lists.postgresql.org
  Subject: Re: doc: Clarify ANALYZE VERBOSE output
  In-Reply-To: <CAP5x3paeoLBgL0jYU-WBcBv0pTKL0nehNZAohCBPdwCmMu6YEg@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox