Re: Overhauling "Routine Vacuuming" docs, particularly its handling of freezing

On Thu, Apr 27, 2023 at 12:58 AM Peter Geoghegan <pg(at)bowt(dot)ie> wrote:
>
> [v2]

I've done a more careful read-through, but I'll need a couple more, I
imagine.

I'll first point out some things I appreciate, and I'm glad are taken care
of as part of this work:

- Pushing the talk of scheduled manual vacuums to the last, rather than
first, para in the intro
- No longer pretending that turning off autovacuum is somehow normal
- Removing the egregiously outdated practice of referring to VACUUM FULL as
a "variant" of VACUUM
- Removing the mention of ALTER TABLE that has no earthly business in this
chapter -- for that, rewriting the table is a side effect to try to avoid,
not a tool in our smorgasbord for removing severe bloat.

Some suggestions:

- The section "Recovering Disk Space" now has 5 tips/notes/warnings in a
row. This is good information, but I wonder about:

"Note: Although VACUUM FULL is technically an option of the VACUUM command,
VACUUM FULL uses a completely different implementation. VACUUM FULL is
essentially a variant of CLUSTER. (The name VACUUM FULL is historical; the
original implementation was somewhat closer to standard VACUUM.)"

...maybe move this to a second paragraph in the warning about VACUUM FULL
and CLUSTER?

- The sentence "The XID cutoff point that VACUUM uses..." reads a bit
abruptly and unmotivated (although it is important). Part of the reason for
this is that the hyperlink "transaction ID number (XID)" which points to
the glossary is further down the page than this first mention.

- "VACUUM often marks certain pages frozen, indicating that all eligible
rows on the page were inserted by a transaction that committed sufficiently
far in the past that the effects of the inserting transaction are certain
to be visible to all current and future transactions."
-> This sentence is much harder to understand than the one it replaces.
Also, this is the first time "eligible" is mentioned. It may not need a
separate definition, but in this form it's rather circular.

- "freezing plays a crucial role in enabling _management of the XID
address_ space by VACUUM"
-> "management of the XID address space" links to the
aggressive-strategy sub-section below, but it's a strange link title
because the section we're in is itself titled "Freezing to manage the
transaction ID space".

- "The maximum “distance” that the system can tolerate..."
-> The next sentence goes on to show the "age" function, so using
different terms is a bit strange. Mixing the established age term with an
in-quotes "distance" could perhaps be done once in a definition, but then
all uses should stick to age.

--
John Naylor
EDB: http://www.enterprisedb.com