agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedClarify VACUUM FULL exclusion in total_vacuum_time docs
12+ messages / 4 participants
[nested] [flat]
* Clarify VACUUM FULL exclusion in total_vacuum_time docs
@ 2025-06-06 11:38 Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Fujii Masao @ 2025-06-06 11:38 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi,
Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
we should add the same clarification to the description of total_vacuum_time.
This field also excludes VACUUM FULL, and without this note, users might
mistakenly think the time spent on VACUUM FULL is included. Thought?
<structfield>total_vacuum_time</structfield> <type>double precision</type>
</para>
<para>
- Total time this table has been manually vacuumed, in milliseconds.
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting <command>VACUUM FULL</command>).
(This includes the time spent sleeping due to cost-based delays.)
</para></entry>
</row>
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
@ 2025-06-06 13:57 ` David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 12+ messages in thread
From: David G. Johnston @ 2025-06-06 13:57 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@oss.nttdata.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
> Hi,
>
> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
> we should add the same clarification to the description of
> total_vacuum_time.
> This field also excludes VACUUM FULL, and without this note, users might
> mistakenly think the time spent on VACUUM FULL is included. Thought?
>
> <structfield>total_vacuum_time</structfield> <type>double
> precision</type>
> </para>
> <para>
> - Total time this table has been manually vacuumed, in milliseconds.
> + Total time this table has been manually vacuumed, in milliseconds
> + (not counting <command>VACUUM FULL</command>).
> (This includes the time spent sleeping due to cost-based delays.)
> </para></entry>
> </row>
>
Makes sense. Our naming this table rewrite vacuum full does confuse
people into thinking it is related to vacuum.
David J.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
@ 2025-06-06 15:13 ` Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 1 reply; 12+ messages in thread
From: Robert Treat @ 2025-06-06 15:13 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
>>
>> Hi,
>>
>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
>> we should add the same clarification to the description of total_vacuum_time.
>> This field also excludes VACUUM FULL, and without this note, users might
>> mistakenly think the time spent on VACUUM FULL is included. Thought?
>>
>> <structfield>total_vacuum_time</structfield> <type>double precision</type>
>> </para>
>> <para>
>> - Total time this table has been manually vacuumed, in milliseconds.
>> + Total time this table has been manually vacuumed, in milliseconds
>> + (not counting <command>VACUUM FULL</command>).
>> (This includes the time spent sleeping due to cost-based delays.)
>> </para></entry>
>> </row>
>
>
> Makes sense. Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.
>
+1 for this change, but I think we should also update
n_ins_since_vacuum as well, no?
Robert Treat
https://xzilla.net
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
@ 2025-06-13 02:28 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 12+ messages in thread
From: Fujii Masao @ 2025-06-13 02:28 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On 2025/06/07 0:13, Robert Treat wrote:
> On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
>> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
>>>
>>> Hi,
>>>
>>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
>>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
>>> we should add the same clarification to the description of total_vacuum_time.
>>> This field also excludes VACUUM FULL, and without this note, users might
>>> mistakenly think the time spent on VACUUM FULL is included. Thought?
>>>
>>> <structfield>total_vacuum_time</structfield> <type>double precision</type>
>>> </para>
>>> <para>
>>> - Total time this table has been manually vacuumed, in milliseconds.
>>> + Total time this table has been manually vacuumed, in milliseconds
>>> + (not counting <command>VACUUM FULL</command>).
>>> (This includes the time spent sleeping due to cost-based delays.)
>>> </para></entry>
>>> </row>
>>
>>
>> Makes sense. Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.
>>
>
> +1 for this change,
Thanks both for the review!
> but I think we should also update
> n_ins_since_vacuum as well, no?
I didn't update n_ins_since_vacuum since it's mainly used by autovacuum rather
than end users, and there haven't been any complaints about the current
description so far. That said, I don't have a strong opinion either way,
so I'm fine with making the change if others think it's worthwhile.
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
@ 2025-06-13 12:09 ` Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 1 reply; 12+ messages in thread
From: Robert Treat @ 2025-06-13 12:09 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@oss.nttdata.com>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Thu, Jun 12, 2025 at 10:28 PM Fujii Masao
<masao.fujii@oss.nttdata.com> wrote:
> On 2025/06/07 0:13, Robert Treat wrote:
> > On Fri, Jun 6, 2025 at 9:57 AM David G. Johnston
> > <david.g.johnston@gmail.com> wrote:
> >> On Friday, June 6, 2025, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
> >>>
> >>> Hi,
> >>>
> >>> Since last_vacuum and vacuum_count in pg_stat_all_tables explicitly mention
> >>> that they don't include VACUUM FULL ("not counting VACUUM FULL"), I think
> >>> we should add the same clarification to the description of total_vacuum_time.
> >>> This field also excludes VACUUM FULL, and without this note, users might
> >>> mistakenly think the time spent on VACUUM FULL is included. Thought?
> >>>
> >>> <structfield>total_vacuum_time</structfield> <type>double precision</type>
> >>> </para>
> >>> <para>
> >>> - Total time this table has been manually vacuumed, in milliseconds.
> >>> + Total time this table has been manually vacuumed, in milliseconds
> >>> + (not counting <command>VACUUM FULL</command>).
> >>> (This includes the time spent sleeping due to cost-based delays.)
> >>> </para></entry>
> >>> </row>
> >>
> >>
> >> Makes sense. Our naming this table rewrite vacuum full does confuse people into thinking it is related to vacuum.
> >>
> >
> > +1 for this change,
>
> Thanks both for the review!
>
>
> > but I think we should also update
> > n_ins_since_vacuum as well, no?
>
> I didn't update n_ins_since_vacuum since it's mainly used by autovacuum rather
> than end users, and there haven't been any complaints about the current
> description so far. That said, I don't have a strong opinion either way,
> so I'm fine with making the change if others think it's worthwhile.
>
Well, I admit I mostly mentioned it because when I noticed this one
wasn't documented the same way the other ones were, I second-guessed
myself about if I knew how it really behaved and did a quick test to
confirm :-)
I suspect others might have similar confusion.
Robert Treat
https://xzilla.net
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
@ 2025-06-17 14:54 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 12+ messages in thread
From: Fujii Masao @ 2025-06-17 14:54 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On 2025/06/13 21:09, Robert Treat wrote:
> Well, I admit I mostly mentioned it because when I noticed this one
> wasn't documented the same way the other ones were, I second-guessed
> myself about if I knew how it really behaved and did a quick test to
> confirm :-)
> I suspect others might have similar confusion.
Maybe I failed to follow your point here... Are you suggesting it's worth
mentioning that n_ins_since_vacuum doesn't count VACUUM FULL, to help
avoid potential user confusion? If so, since n_ins_since_vacuum was
introduced in v13, we'd need to backpatch that documentation change to v13?
As for total_vacuum_time, since it's new in v18, I'd like to apply
the proposed change there.
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
@ 2025-06-17 21:53 ` Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 1 reply; 12+ messages in thread
From: Robert Treat @ 2025-06-17 21:53 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@oss.nttdata.com>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tue, Jun 17, 2025 at 10:54 AM Fujii Masao
<masao.fujii@oss.nttdata.com> wrote:
> On 2025/06/13 21:09, Robert Treat wrote:
> > Well, I admit I mostly mentioned it because when I noticed this one
> > wasn't documented the same way the other ones were, I second-guessed
> > myself about if I knew how it really behaved and did a quick test to
> > confirm :-)
> > I suspect others might have similar confusion.
>
> Maybe I failed to follow your point here... Are you suggesting it's worth
> mentioning that n_ins_since_vacuum doesn't count VACUUM FULL, to help
> avoid potential user confusion? If so, since n_ins_since_vacuum was
> introduced in v13, we'd need to backpatch that documentation change to v13?
>
> As for total_vacuum_time, since it's new in v18, I'd like to apply
> the proposed change there.
>
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.
Robert Treat
https://xzilla.net
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
@ 2025-07-14 16:51 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-07-15 05:44 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 12+ messages in thread
From: Fujii Masao @ 2025-07-14 16:51 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
From b1e64ee62915b883369a46e6add417acde15da88 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 15 Jul 2025 01:21:24 +0900
Subject: [PATCH v1] doc: Clarify that total_vacuum_time excludes VACUUM FULL.
The last_vacuum and vacuum_count fields in pg_stat_all_tables already
state that they do not include VACUUM FULL. However, total_vacuum_time,
which also excludes VACUUM FULL, did not mention this. This could
mislead users into thinking VACUUM FULL time is included.
To address this, this commit updates the documentation for
pg_stat_all_tables to explicitly state that total_vacuum_time does not
count VACUUM FULL.
Back-patched to v18, where total_vacuum_time was introduced.
Additionally, this commit clarifies that n_ins_since_vacuum also
excludes VACUUM FULL. Although n_ins_since_vacuum was added in v13,
we are not back-patching this change to stable branches, as it is
a documentation improvement, not a bug fix.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com
Backpatch-through: 18
---
doc/src/sgml/monitoring.sgml | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 4265a22d4de..823afe1b30b 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3980,6 +3980,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Estimated number of rows inserted since this table was last vacuumed
+ (not counting <command>VACUUM FULL</command>)
</para></entry>
</row>
@@ -4066,7 +4067,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
<structfield>total_vacuum_time</structfield> <type>double precision</type>
</para>
<para>
- Total time this table has been manually vacuumed, in milliseconds.
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting <command>VACUUM FULL</command>).
(This includes the time spent sleeping due to cost-based delays.)
</para></entry>
</row>
--
2.49.0
Attachments:
[text/plain] v1-0001-doc-Clarify-that-total_vacuum_time-excludes-VACUU.patch (2.3K, ../../b1cfd248-6860-4a95-bb62-07009f5e486e@oss.nttdata.com/2-v1-0001-doc-Clarify-that-total_vacuum_time-excludes-VACUU.patch)
download | inline diff:
From b1e64ee62915b883369a46e6add417acde15da88 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 15 Jul 2025 01:21:24 +0900
Subject: [PATCH v1] doc: Clarify that total_vacuum_time excludes VACUUM FULL.
The last_vacuum and vacuum_count fields in pg_stat_all_tables already
state that they do not include VACUUM FULL. However, total_vacuum_time,
which also excludes VACUUM FULL, did not mention this. This could
mislead users into thinking VACUUM FULL time is included.
To address this, this commit updates the documentation for
pg_stat_all_tables to explicitly state that total_vacuum_time does not
count VACUUM FULL.
Back-patched to v18, where total_vacuum_time was introduced.
Additionally, this commit clarifies that n_ins_since_vacuum also
excludes VACUUM FULL. Although n_ins_since_vacuum was added in v13,
we are not back-patching this change to stable branches, as it is
a documentation improvement, not a bug fix.
Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/2ac375d1-591b-4f1b-a2af-f24335567866@oss.nttdata.com
Backpatch-through: 18
---
doc/src/sgml/monitoring.sgml | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 4265a22d4de..823afe1b30b 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3980,6 +3980,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Estimated number of rows inserted since this table was last vacuumed
+ (not counting <command>VACUUM FULL</command>)
</para></entry>
</row>
@@ -4066,7 +4067,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
<structfield>total_vacuum_time</structfield> <type>double precision</type>
</para>
<para>
- Total time this table has been manually vacuumed, in milliseconds.
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting <command>VACUUM FULL</command>).
(This includes the time spent sleeping due to cost-based delays.)
</para></entry>
</row>
--
2.49.0
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
@ 2025-07-15 05:44 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 14:27 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 12+ messages in thread
From: Laurenz Albe @ 2025-07-15 05:44 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@oss.nttdata.com>; Robert Treat <rob@xzilla.net>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-07-15 05:44 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Laurenz Albe <laurenz.albe@cybertec.at>
@ 2025-07-15 14:27 ` Robert Treat <rob@xzilla.net>
2025-07-15 16:27 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 23:12 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 2 replies; 12+ messages in thread
From: Robert Treat @ 2025-07-15 14:27 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tue, Jul 15, 2025 at 1:44 AM Laurenz Albe <laurenz.albe@cybertec.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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-07-15 05:44 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 14:27 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
@ 2025-07-15 16:27 ` Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 0 replies; 12+ messages in thread
From: Laurenz Albe @ 2025-07-15 16:27 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; David G. Johnston <david.g.johnston@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tue, 2025-07-15 at 10:27 -0400, Robert Treat wrote:
> 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.
Makes sense, and I have no objection to the patch as it is.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-07-15 05:44 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 14:27 ` Re: Clarify VACUUM FULL exclusion in total_vacuum_time docs Robert Treat <rob@xzilla.net>
@ 2025-07-15 23:12 ` Fujii Masao <masao.fujii@oss.nttdata.com>
1 sibling, 0 replies; 12+ messages in thread
From: Fujii Masao @ 2025-07-15 23:12 UTC (permalink / raw)
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>
On 2025/07/15 23:27, Robert Treat wrote:
> On Tue, Jul 15, 2025 at 1:44 AM Laurenz Albe <laurenz.albe@cybertec.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.
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,
--
Fujii Masao
NTT DATA Japan Corporation
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2025-07-15 23:12 UTC | newest]
Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-06-06 11:38 Clarify VACUUM FULL exclusion in total_vacuum_time docs Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-06 13:57 ` David G. Johnston <david.g.johnston@gmail.com>
2025-06-06 15:13 ` Robert Treat <rob@xzilla.net>
2025-06-13 02:28 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-13 12:09 ` Robert Treat <rob@xzilla.net>
2025-06-17 14:54 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-06-17 21:53 ` Robert Treat <rob@xzilla.net>
2025-07-14 16:51 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2025-07-15 05:44 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 14:27 ` Robert Treat <rob@xzilla.net>
2025-07-15 16:27 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-07-15 23:12 ` Fujii Masao <masao.fujii@oss.nttdata.com>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox