MIME-Version: 1.0
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Mon, 6 Jan 2025 19:12:53 -0500
Message-ID: 
 <CAAKRu_aQUOaMYrcjNuXeSkJtaX9oRUzKP57bsYbC0gVVWS+cbA@mail.gmail.com>
Subject: Moving the vacuum GUCs' docs out of the Client Connection Defaults
 section
To: Pg Hackers <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Archived-At: 
 <https://www.postgresql.org/message-id/CAAKRu_aQUOaMYrcjNuXeSkJtaX9oRUzKP57bsYbC0gVVWS%2BcbA%40mail.gmail.com>
Precedence: bulk

I was reviewing all the vacuum related GUCs, and I noticed that they
fall into three main subsections of Chapter 19 (Server Configuration)
in the docs [1]: Automatic Vacuuming [2], Resource Consumption [3],
and Client Connection Defaults [4]. The last one I find pretty
confusing.

vacuum_freeze_min_age, vacuum_freeze_table_age, vacuum_failsafe_age
and their multixact equivalents are all in the Statement Behavior
subsection of the Client Connection Defaults subsection. I could maybe
see a justification for this if these GUCs only affected VACUUM
statements -- but that's not the case. All of these GUCs affect the
behavior of both manually invoked vacuums and autovacuums (with some
caveats about precedence when equivalent table storage parameters are
specified).
But maybe there is some other reason they are documented there that I
am missing.
If not, maybe we should fix it?

I'm not totally sure what the solution should be. Perhaps we rename
the "Automatic Vacuuming" subsection "Vacuuming" and then make
"Automatic Vacuuming" a sub-subsection? And move the vacuum-related
GUCs from client connection defaults to "Vacuuming"?

- Melanie

[1] https://www.postgresql.org/docs/17/runtime-config.html
[2] https://www.postgresql.org/docs/17/runtime-config-autovacuum.html
[3] https://www.postgresql.org/docs/17/runtime-config-resource.html
[4] https://www.postgresql.org/docs/17/runtime-config-client.html