Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs

On Tue, Jul 15, 2025 at 1:44 AM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)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 like
> > > 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 new
> > > 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.
>
> 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.
>

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.

Robert Treat
https://xzilla.net