Message-ID: <b27ed7be-4289-4109-ad78-6d427af4d8d0@oss.nttdata.com>
Date: Wed, 16 Jul 2025 08:12:22 +0900
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
To: Robert Treat <rob@xzilla.net>, Laurenz Albe <laurenz.albe@cybertec.at>
Cc: "David G. Johnston" <david.g.johnston@gmail.com>,
 "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
References: <2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com>
 <CAKFQuwYgErraNuAUme-6dSwmwNSSStC8SL7560Qy2sAtUG5J+Q@mail.gmail.com>
 <CABV9wwMs4g9nq-fKy=fFqU-rQUf6fiCqJg4_+MkqOnJE1n2TBA@mail.gmail.com>
 <f58eb77f-0d8f-4f58-bed2-a100bd7e0814@oss.nttdata.com>
 <CAJSLCQ3YPKaB7tQDyg8BbVuo80EGn_j6kycNGG3oZB59P8tgrg@mail.gmail.com>
 <bb97b8d4-2f44-4b95-9b82-a54ecbce9e76@oss.nttdata.com>
 <CAJSLCQ27T5utjOipbaqArGCPS1VT+2Uqx_g2NH3od_spHxkoig@mail.gmail.com>
 <b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com>
 <213ce4a8cc0e481229bdf2198f5c44285eb3e53a.camel@cybertec.at>
 <CAJSLCQ0Sh5YsOfdMXdTQQzTC2gVgVQdrkUekDvk_cvPj7p5YPA@mail.gmail.com>
Content-Language: en-US
From: Fujii Masao <masao.fujii@oss.nttdata.com>
In-Reply-To: 
 <CAJSLCQ0Sh5YsOfdMXdTQQzTC2gVgVQdrkUekDvk_cvPj7p5YPA@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/b27ed7be-4289-4109-ad78-6d427af4d8d0%40oss.nttdata.com>
Precedence: bulk


On 2025/07/15 23:27, Robert Treat wrote:
> On Tue, Jul 15, 2025 at 1:44=E2=80=AFAM Laurenz Albe <laurenz.albe@cybe=
rtec.at> wrote:
>>
>> On Tue, 2025-07-15 at 01:51 +0900, Fujii Masao wrote:
>>>
>>> On 2025/06/18 6:53, Robert Treat wrote:
>>>> I think the more cases where you document this behavior (and I do li=
ke
>>>> the idea of documenting it for total_vacuum_time), the more one is
>>>> likely to think that places where it is not documented operate
>>>> differently. To that end, I think documenting it for
>>>> n_ins_since_vacuum as well is a good idea, but I don't feel strongly
>>>> that it needs to be backpatched; the old documentation wasn't wrong
>>>> per se, rather this is a documentation improvement as a result of ne=
w
>>>> development.
>>>
>>> Agreed. The attached patch updates the docs to clarify that both
>>> total_vacuum_time and n_ins_since_vacuum exclude VACUUM FULL.
>>>
>>> Unless there are any objections, I'll commit this to master and
>>> back-patch it to v18 only.

Done, thanks!


>> I think the patch is good.
>>
>> One question for me is whether we should use "VACUUM (FULL)" rather
>> than "VACUUM FULL".
>>
>> On the one hand, the documentation (and most users) still use the
>> old syntax without parentheses almost everywhere.
>>
>> On the other hand, reading the VACUUM reference page, I get the
>> feeling that the new syntax with parentheses should be favored.
>> After all, the old syntax doesn't support any of the recently
>> added options and restricts the option order.
>>
>> So perhaps we should start propagating the parentheses more, and
>> the documentation is the perfect place to do that.

I'm not sure if changing it to "VACUUM (FULL)" is a good idea.
In several places, the docs use "VACUUM FULL" to refer to the full vacuum
operation as a name, rather than the exact command syntax. Changing
all instances to "VACUUM (FULL)" might make the docs harder to read for
users already familiar with the term "VACUUM FULL".

That said, if many others prefer switching to "VACUUM (FULL)",
I have no strong objection. In that case, we might also consider
changing "EXPLAIN ANALYZE" to "EXPLAIN (ANALYZE)" for the same reason.


> That might make sense, but how far we want to take it in the first go
> around seems like a discussion that is best put forth in a separate
> thread / patch.

+1

Regards,

--=20
Fujii Masao
NTT DATA Japan Corporation