Thread: Document WAL rules related to PD_ALL_VISIBLE in README

Document WAL rules related to PD_ALL_VISIBLE in README

From
Jeff Davis
Date:
Proposed wording attached.

The typical WAL rules are broken for setting PD_ALL_VISIBLE. I'm OK
with that -- rules are meant to be broken -- but it's confusing enough
that I think we should (internally) document it better. This doesn't
guarantee things won't change again in the future, but this behavior
has been stable for a while.

The thread here:

https://postgr.es/m/ee47ee24-2928-96e3-a2b1-97cbe07b2c7b%40garret.ru

also indicates that external projects and tools are relying on our
rules for the page LSNs.

Regards,
    Jeff Davis


Attachment

Re: Document WAL rules related to PD_ALL_VISIBLE in README

From
Peter Geoghegan
Date:
On Fri, Nov 11, 2022 at 2:14 PM Jeff Davis <pgsql@j-davis.com> wrote:
> The typical WAL rules are broken for setting PD_ALL_VISIBLE. I'm OK
> with that -- rules are meant to be broken -- but it's confusing enough
> that I think we should (internally) document it better.

+1. I think that there is a lot of value in being deliberate about
invariants like this.

If it's too awkward to list special cases like this one in some
central place, then maybe those special cases shouldn't exist in the
first place. I don't love the fact that we have this PD_ALL_VISIBLE
special case -- "it's kind of a hint but also not really" doesn't
inspire confidence. But I don't see it changing anytime soon.

Acknowledging that it is an odd special case in a full throated sort
of way at least minimizes confusion. It kind of makes sense in one
way, I suppose -- maybe the visibility map itself is the special case.
The visibility map has its own unique definition of crash safe that
makes losing set bits tolerable, while failing to unset a bit remains
intolerable (only the latter could result in wrong answers to
queries). I think that every other on-disk structure is either a pure
hint without any accompanying WAL record, or an atomic action with a
WAL record whose REDO routine needs to reliably reproduce the same
on-disk state as original execution (barring preexisting differences
in how hint bits are set between original execution and a hot
standby).

-- 
Peter Geoghegan