Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1wCPmJ-001xmZ-0D for pgsql-docs@arkaria.postgresql.org; Mon, 13 Apr 2026 22:29:11 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.96) (envelope-from ) id 1wCPmH-008uEf-06 for pgsql-docs@arkaria.postgresql.org; Mon, 13 Apr 2026 22:29:09 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1wCPmG-008uEX-2F for pgsql-docs@lists.postgresql.org; Mon, 13 Apr 2026 22:29:09 +0000 Received: from mail-yx1-xb129.google.com ([2607:f8b0:4864:20::b129]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.98.2) (envelope-from ) id 1wCPmE-00000000vK1-45Rz for pgsql-docs@lists.postgresql.org; Mon, 13 Apr 2026 22:29:08 +0000 Received: by mail-yx1-xb129.google.com with SMTP id 956f58d0204a3-651b4d09141so2974975d50.1 for ; Mon, 13 Apr 2026 15:29:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1776119345; cv=none; d=google.com; s=arc-20240605; b=OgmzO+pxvp3vhbpXbVhRiObuaYs5jbBp4IIkeKgr2d6wPqfjpWddMA7zcnvcQ7faGo MdYKNuK3Bw4B/noDa6xB8Ccd8hUyziW0BWCZt+hBlLyq7xPKnNQ5bEOVSg7FPFLCIi/d 3M4NQn7lUXUkt8Rhr1n2bfSxnaz1FCxTXJPZIykfEiYYF3EDEoWZZgnnkhutBFQ3V2DZ up41kxpk7jSK0z9VryrsQneFjgnk0Z5nyI1pzqa100POsF0NgFuho8puhwzMCbUsVTb1 JmtueWx60O7suKZcv9DnJsMeisll3B4XNEFrixN++gph3m0YVv5DLc0aIY1avdGm6EK7 cs/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:dkim-signature; bh=0JlJkcUaejOxpvqKwLTyh+GT52dyS3m3j/8nEwF+UuI=; fh=aiX3LI0NO18J1A/Pcdxsv5fmhIN+hC8X3PfkgpTdyi0=; b=GUtk692koPP0rDi0gtsK8GO9KYjRFM3c0I/r4qn68SF1cemJLH42+595OZLDqDlNri emvFaJcCIwoJ5vlhmAi3rACuT7hf2mPpU8qsG0Xfw1AwkIkkr1dbW0NWHDjw4qLfkJQu p/+COlruQjpqA/qjc1kjWhdGTcWGATUKatkHhrb5q4eEd+yCSbvKYRVedF7ZmVR7/geR SJ7DKQnD/xH2CJM5VKXD+ffF++HXnv63hrthsy2gAvtrS9HtC+M9OPs9flBhxxkECCsw cygLVZsvqmpRS6Ssfsqo8KtTT/lP3L1dKoreVb1BumxbWdZTSo2JJxAGcfvD5yh+TcZ7 BwdA==; darn=lists.postgresql.org ARC-Authentication-Results: i=1; mx.google.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1776119345; x=1776724145; darn=lists.postgresql.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=0JlJkcUaejOxpvqKwLTyh+GT52dyS3m3j/8nEwF+UuI=; b=RdfSgdGPPivjcN3ye0NABdEe5Asr4QJFEqs58SQxLsFQikCYtGoOWLAB2smnn1J073 4d70HqpZZNkwZf1+kC9Enw9c/qlPpn+mx4JreqtQow8I9d1afms3f42SxpUJhNunFFlQ yYAt9Fk2gCK1GXDEu0pNI501NVsckWG4BApW92yDe2Gv90PJ/euSFxRUlZUPYl5f4eUl +QSO/YPNl75U/tAatwEWR47vXF6eqmHkIDNei4dHTZmHQHh9emR9eokgc2FCnHJMe+y2 joNptNPW/0RaQR0JEXhUMaXmaoaK2Gb8ZKueC2SexHYrBk3Cu6NmwzetnA8oE3d6QiiH xS+Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1776119345; x=1776724145; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=0JlJkcUaejOxpvqKwLTyh+GT52dyS3m3j/8nEwF+UuI=; b=VgJls9fLsZxMb6LgGePHb2OHOWK04yBkmTna1QgQWSJp1viXVLNDmdQ7R0E0LS78+9 4iKkKIfAFeaUcGlAJ11+bk22UbeWa6hn729NnMuOSXFruDtERM3emKKd8sYthDdQ+JN7 qqBZh+AqcZFVp/QwI6r+niMy1YzkqGLad8Szl3Wt0UaPyyftsMk5BdC3wDTWfLSrq+yJ DoZGnR/H9uh7jJS/Z/p43JbDn69Q3HupNOJv+VgE4CD5fb54wF23wkqXzydiX4q/CanJ TisidUY1FC9h1ECAD4V4jURTwABOAbdjMxCAPUxTlCcOZED96Fjt6o+70D1NHK2vGi9I KyPg== X-Forwarded-Encrypted: i=1; AFNElJ+ZA8miXMlRTh+lpDjjU/CyvzlxK5XfQz8JldhzZih3HeYE9TIyQr6E0BJZ5CQ2HDI6t3Yje/V3Ugwv@lists.postgresql.org X-Gm-Message-State: AOJu0YwziEDtl48/FuunHysRtJxquLnoVobPekkXW3TFoVDVLMFY+8Jb oJU3lpFSzqGWN0ijgtSlHcUdT0qIIF5ZWlOXKJtlXNbFxTFA/RzMJQali02pp1zpo9fx9DK0Dff lUJ53BRF+4Hs5e4CG9s+zmB3W5URN8xM= X-Gm-Gg: AeBDieuCK3lVXRwHlRuERQq6DMuqHuN7nJ82XRU+uQ1CwKlB6waHXcSEEYWBFnsKu0j y1hFpaP6BeFy4XHeS7Ot7bpYe6j3py5ql0r5C6+Ot+NHiacSCxZeddU+YWztQzN7SralW5o4WiR Amqr0r2kcTVSlcaLg+A3kaDzzDNVpCR3KnQ2xClh4EsLn1OgxW1lgWE58/6yzri80hj0ZIjXNyb 82OaH+jZoX53S9I7U1PTIf2U/QpU4ir4k70at8AsBPTEkkRjc2bnZogISSDsCgnt9hTQ3Km7cC6 id3m4xKTLtXU+sS/Ew== X-Received: by 2002:a05:690e:1289:b0:651:e1e7:7f51 with SMTP id 956f58d0204a3-651e1e79287mr403659d50.31.1776119345011; Mon, 13 Apr 2026 15:29:05 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: "David G. Johnston" Date: Mon, 13 Apr 2026 15:28:28 -0700 X-Gm-Features: AQROBzClQ3KH2lohQktmJ-RIu8XboGVzz-p0w1hxHRWetHQq8T0BjGPOLrulWGo Message-ID: Subject: Re: doc: Clarify ANALYZE VERBOSE output To: maciek@sakrejda.org Cc: Shinya Kato , Fujii Masao , pgsql-docs@lists.postgresql.org Content-Type: multipart/alternative; boundary="000000000000a35fa0064f5f0266" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000a35fa0064f5f0266 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Mon, Apr 13, 2026 at 2:28=E2=80=AFPM Maciek Sakrejda wrote: > On Tue, Apr 7, 2026 at 6:57=E2=80=AFPM Shinya Kato > wrote: > > On Mon, Apr 6, 2026, 14:17 David G. Johnston > wrote: > >> > >> How about something like: > >> =E2=80=9CEnables sending an INFO message to the client (and server log= ) as each > table is processed. This message contains: etc=E2=80=A6=E2=80=9D > >> > >> And then let=E2=80=99s tell the user what info they are getting and wh= at it > means (where necessary). > >> > >> I concur being specific about when these messages arrive, and IMO > where, should be specified. But losing the detail of =E2=80=9Creport=E2= =80=9D 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 update= s. > > > > 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 INFO 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. --000000000000a35fa0064f5f0266 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Mon, Apr 13, 2026 at 2:28=E2=80=AFPM Maciek Sakrejda &l= t;m.sakrejda@gmail.com> wrot= e:
On Tue, Apr 7, 2026 at 6:57=E2= =80=AFPM Shinya Kato <shinya11.kato@gmail.com> wrote:
> On Mon, Apr 6, 2026, 14:17 David G. Johnston <david.g.johnston@gmail.com&g= t; wrote:
>>
>> How about something like:
>> =E2=80=9CEnables sending an INFO message to the client (and server= log) as each table is processed.=C2=A0 This message contains: etc=E2=80=A6= =E2=80=9D
>>
>> And then let=E2=80=99s tell the user what info they are getting an= d what it means (where necessary).
>>
>> I concur being specific about when these messages arrive, and IMO = where, should be specified.=C2=A0 But losing the detail of =E2=80=9Creport= =E2=80=9D is not good; but not sure why we are being vague so suggest we ju= st go all-in on specificity.
>
> Thank you for the suggestion. I'd prefer to keep this patch focuse= d; 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 kep= t simple to minimize maintenance overhead. While expanding it might be a wo= rthwhile 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 t= he fact this is user-facing output, I'm not seeing why this gets a pass= on the documentation requirement.=C2=A0 That said, I concur this patch nee= dn't be responsible for dealing with that - I'm not even sure wheth= er 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 t= o vacuum itself.=C2=A0 Though stuff like timings are.=C2=A0 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 fo= r each table
as it is processed."


I really do= n't like the word "Print" here.=C2=A0 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 f= ile though.

So that leaves me with suggesting:

"Enables the sending of a detailed INFO message to the c= lient after each table is processed."

David J.

--000000000000a35fa0064f5f0266--