Re: Improving the "Routine Vacuuming" docs

On Wed, Apr 13, 2022 at 2:19 PM Peter Geoghegan <pg(at)bowt(dot)ie> wrote:

> On Wed, Apr 13, 2022 at 1:25 PM Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> > On Wed, Apr 13, 2022 at 12:34 PM Peter Geoghegan <pg(at)bowt(dot)ie> wrote:
> > > What do you think of the idea of relating freezing to removing tuples
> > > by VACUUM at this point? This would be a basis for explaining how
> > > freezing and tuple removal are constrained by the same cutoff.
>
> > I think something like that could be useful, if we can find a way to
> > word it sufficiently clearly.
>
> What if the current "25.1.5. Preventing Transaction ID
> Wraparound Failures" section was split into two parts? The first part
> would cover freezing, the second part would cover
> relfrozenxid/relminmxid advancement.
>
> Freezing can sensibly be discussed before introducing relfrozenxid.
> Freezing is a maintenance task that makes tuples self-contained
> things, suitable for long term storage. Freezing makes tuples not rely
> on transient transaction metadata (mainly clog), and so is an overhead
> of storing data in Postgres long term.
>
> That's how I think of it, at least. That definition seems natural to me.
>

I was trying to do that with my second try, and partially failed. I'm on
board with the idea though.

> > Those all sound pretty reasonable.
>
> Great.
>
> I have two more things that I see as problems. Would be good to get
> your thoughts here, too. They are:
>
> 1. We shouldn't really be discussing VACUUM FULL here at all, except
> to say that it's out of scope, and probably a bad idea.
>
> You once wrote about the problem of how VACUUM FULL is perceived by
> users (VACUUM FULL doesn't mean "VACUUM, but better"), expressing an
> opinion of VACUUM FULL that I agree with fully. The docs definitely
> contributed to that problem.
>

I agree. I would remove VACUUM FULL from the "Vacuuming Basics" and
"Recovering Disk Space" section aside from adding a warning box saying it
exists, it is not part of routine maintenance (hence out-of-scope for the
"Routine Vacuuming" Chapter), and to look elsewhere for details.

>
> 2. We don't go far enough in emphasizing the central role of autovacuum.
>
> Technically the entire section assumes that its primary audience are
> those users that have opted to not use autovacuum. This seems entirely
> backwards to me.
>

I would be on board with having the language of the entire section written
with the assumption that autovacuum is enabled, with a single statement
upfront that this is the case. Most of the content remains as-is but we
remove a non-trivial number of sentences and fragments of the form "The
autovacuum daemon, if enabled, will..." and "For those not using
autovacuum,..."

If the basic content is deemed worthy of preservation, relocating all of
those kinds of hints and whatnot to a single "supplementing or disabling
auto-vacuum" section.

> > There's a little bit of doubt in my
> > mind about the third one; I think it could possibly be useful to
> > explain that the XID space is circular and 0-2 are special, but maybe
> > not.
>
> I understand the concern. I'm not saying that this kind of information
> doesn't have any business being in the docs. Just that it has no
> business being in this particular chapter of the docs. In fact, it
> doesn't even belong in "III. Server Administration". If it belongs
> anywhere, it should be in some chapter from "VII. Internals".
>

I think we do want to relocate some of this material elsewhere, and
Internals seems probable, and we'd want to have a brief sentence or two
here before pointing the reader to more information. I'm sure we'll come
to some conclusion on the level of detail that lead-in should include.
Less is more to start with. Unless the rest of the revised chapter is
going to lean heavily into it.

>
> Why shouldn't single-user mode also refuse to allocate new XIDs when
> we reach xidWrapLimit (as opposed to when we reach xidStopLimit)?
>
>
I lack the familiarity with the details here to comment on this last major
point.

I do think the "Server Administration" section is missing a chapter though
- "Error Handling and Recovery".

With that chapter in place I would mention the warning threshold in the
routine maintenance chapter as something that might be seen if routine
maintenance is misconfigured or encounters problems. Then direct the user
to "Error Handling and Recovery" for discussion about the warning and
whatever else may happen if it is ignored; and how to go about fixing the
problem(s) that caused the warning.

David J.