Thread: Per-table log_autovacuum_min_duration is actually documented
Hi all, While going through the release notes of 9.5 I noticed the following chunk in doc/src/sgml/release-9.5.sgml: Add per-table autovacuum logging control via log_min_autovacuum_duration (Michael Paquier) NOT DOCUMENTED? This is actually documented in src/sgml/ref/create_table.sgml with the following paragraph so this mention in the release notes does not seem needed: log_autovacuum_min_duration, toast.log_autovacuum_min_duration (integer) Custom log_autovacuum_min_duration parameter. I recall that we had some talks about grouping all the relopts into a single documentation section, perhaps not having one is at the origin of the confusion? Regards, -- Michael
Michael Paquier <michael.paquier@gmail.com> writes:
> While going through the release notes of 9.5 I noticed the following
> chunk in doc/src/sgml/release-9.5.sgml:
> Add per-table autovacuum logging control via
> log_min_autovacuum_duration (Michael Paquier)
> NOT DOCUMENTED?
Yeah ... I was going to do something about that on Sunday, until I got
sidetracked by the docs build blowing up on me ...
> This is actually documented in src/sgml/ref/create_table.sgml with the
> following paragraph so this mention in the release notes does not seem
> needed:
> log_autovacuum_min_duration, toast.log_autovacuum_min_duration (integer)
> Custom log_autovacuum_min_duration parameter.
Hmm ... that doesn't seem exactly transparent; what does "custom" mean?
Should it read "Overrides log_autovacuum_min_duration for autovacuum
operations on this specific table or toast table"?
regards, tom lane
On Wed, Nov 11, 2015 at 12:07 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Michael Paquier <michael.paquier@gmail.com> writes: >> This is actually documented in src/sgml/ref/create_table.sgml with the >> following paragraph so this mention in the release notes does not seem >> needed: >> log_autovacuum_min_duration, toast.log_autovacuum_min_duration (integer) >> Custom log_autovacuum_min_duration parameter. > > Hmm ... that doesn't seem exactly transparent; what does "custom" mean? In this context, "custom" means a per-table value that is used instead of the server-wide value if defined. Its toast equivalent uses the per-table value if not defined explicitly. The other autovacuum parameters are using the same formulation. > Should it read "Overrides log_autovacuum_min_duration for autovacuum > operations on this specific table or toast table"? The same applied for all the other autovacuum and autoanalyze parameters. Do you think that we should add in the top paragraph of section "Storage Parameters" a mention of the type "If this parameter has a server-wide equivalent parameter, the per-table value overrides its server-wide equivalent if defined" or similar. -- Michael
Michael Paquier <michael.paquier@gmail.com> writes:
> On Wed, Nov 11, 2015 at 12:07 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Should it read "Overrides log_autovacuum_min_duration for autovacuum
>> operations on this specific table or toast table"?
> The same applied for all the other autovacuum and autoanalyze
> parameters. Do you think that we should add in the top paragraph of
> section "Storage Parameters" a mention of the type "If this parameter
> has a server-wide equivalent parameter, the per-table value overrides
> its server-wide equivalent if defined" or similar.
There's a whole lot of inconsistency in this area, apparently. Some of
the entries in runtime-config-autovacuum are marked as being overridable
by storage parameters, some aren't (in particular this one is not, which
may be the origin of Bruce's complaint). Some of the entries in
SQL-CREATETABLE-storage-parameters use the "custom" phraseology, some
don't but instead duplicate (or more often, rephrase poorly) the
documentation of the underlying GUC. I think duplication is a bad
strategy here. But I still don't care for "custom", perhaps because it's
been stretched to the point of being nearly meaningless elsewhere in the
system. "Per-table" is used in other sentences in this same area, and
that seems like a better description.
I'll try to make this better.
regards, tom lane
Tom Lane wrote: > Michael Paquier <michael.paquier@gmail.com> writes: > > On Wed, Nov 11, 2015 at 12:07 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > >> Should it read "Overrides log_autovacuum_min_duration for autovacuum > >> operations on this specific table or toast table"? > > > The same applied for all the other autovacuum and autoanalyze > > parameters. Do you think that we should add in the top paragraph of > > section "Storage Parameters" a mention of the type "If this parameter > > has a server-wide equivalent parameter, the per-table value overrides > > its server-wide equivalent if defined" or similar. > > There's a whole lot of inconsistency in this area, apparently. Some of > the entries in runtime-config-autovacuum are marked as being overridable > by storage parameters, some aren't (in particular this one is not, which > may be the origin of Bruce's complaint). log_autovacuum_min_duration was made changeable per-table recently by commit 4ff695b17d32 of April 2015, having been introduced by commit 9d3b50244357ef4, Nov 2011, while the others have been changeable for a much longer while, c.f. 834a6da4f72d of Feb 2009. > Some of the entries in > SQL-CREATETABLE-storage-parameters use the "custom" phraseology, some > don't but instead duplicate (or more often, rephrase poorly) the > documentation of the underlying GUC. I think duplication is a bad > strategy here. But I still don't care for "custom", perhaps because it's > been stretched to the point of being nearly meaningless elsewhere in the > system. "Per-table" is used in other sentences in this same area, and > that seems like a better description. Sounds fair. > I'll try to make this better. Thanks! -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Michael Paquier wrote: > I recall that we had some talks about grouping all the relopts into a > single documentation section, perhaps not having one is at the origin > of the confusion? I think you're remembering this: http://www.postgresql.org/message-id/20150402205713.GB22175@eldon.alvh.no-ip.org -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, Nov 12, 2015 at 6:27 AM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > Michael Paquier wrote: > >> I recall that we had some talks about grouping all the relopts into a >> single documentation section, perhaps not having one is at the origin >> of the confusion? > > I think you're remembering this: > http://www.postgresql.org/message-id/20150402205713.GB22175@eldon.alvh.no-ip.org Right. Thanks. Do you think we'd still want a patch to improve that? -- Michael
Michael Paquier <michael.paquier@gmail.com> writes: > On Thu, Nov 12, 2015 at 6:27 AM, Alvaro Herrera > <alvherre@2ndquadrant.com> wrote: >> I think you're remembering this: >> http://www.postgresql.org/message-id/20150402205713.GB22175@eldon.alvh.no-ip.org > Right. Thanks. Do you think we'd still want a patch to improve that? Give it a try if you like, and see whether it seems to improve matters. I did not try moving material around like that in the patch I committed earlier today. regards, tom lane
On Thu, Nov 12, 2015 at 9:06 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Michael Paquier <michael.paquier@gmail.com> writes: >> On Thu, Nov 12, 2015 at 6:27 AM, Alvaro Herrera >> <alvherre@2ndquadrant.com> wrote: >>> I think you're remembering this: >>> http://www.postgresql.org/message-id/20150402205713.GB22175@eldon.alvh.no-ip.org > >> Right. Thanks. Do you think we'd still want a patch to improve that? > > Give it a try if you like, and see whether it seems to improve matters. > I did not try moving material around like that in the patch I committed > earlier today. Hm. I am not sure we are quite at the point of hacking something. The pinpoint regarding such a change would be where to gather a description of all those storage parameters, which are already divided by type: per-table and per-index. A new section called "Storage Parameters" in the chapter "Server Configuration", just after "Query Planning" for example would make sense. Then we could have a section for indexes parameters, one for tables, and one for parameters shared between both, like fillfactor. Then we would need to add to link to this new section in the pages of CREATE/ALTER TABLE/INDEX. Does that make sense? The fact that we have per-index and per-table parameters is perhaps an argument sufficient to keep things the way they are now, though we had better add an indexterm for example for fillfactor. -- Michael