Re: max_wal_size

On Thu, May 28, 2020 at 2:21 AM <p(dot)luzanov(at)postgrespro(dot)ru> wrote:

>
> Now we have the glossary. According to the glossary, a checkpoint has two
> meanings.
>
> The first meaning is that this is a point:
> "A point in the WAL sequence at which it is guaranteed that the heap and
> index data files have been updated with all information from shared memory
> modified before that checkpoint; a checkpoint record is written and flushed
> to WAL to mark that point."
>
> The second meaning is that this is an action (performed by checkpointer
> process or CP):
> "A checkpoint is also the act of carrying out all the actions that are
> necessary to reach a checkpoint as defined above."
>
> As I understand now, this is true when we talk about the checkpoint as a
> process.
> "Maximum size to let the WAL grow to between a(b) and b(e), between b(b)
> and c(e), etc".
>
> But this not true when we talk about the checkpoint as a point.
> "Maximum size to let the WAL grow to between A and B".
>
> My concerns that someone reading the description of the parameter may
> confuse the two meanings of checkpoint: as a point and as a process. After
> all, this happened to me.
>

Illuminating perspective. The question for the documentation then becomes
do we introduce the concept of a "checkpoint point/record" here to try and
clear up a possible (but I'd argue rare) misunderstanding at the risk of
complicating things for the reader who only has the process meaning in
mind. This is a tuning knob for the system and, as with the other two that
reference "time", it almost by necessity deals with a process/verb
interpretation of checkpoint, not the point/noun one. While I'm quite
familiar with the presence of the noun meaning it didn't even occur to me
to frame the discussion in those terms. As above, I'm not immediately
convinced that that is a bad thing.

I don't know whether a change along those lines to the configuration
reference page is useful or not - I wouldn't make one without a
comprehensive re-read of the actual background/learning section of the
documentation. My gut instinct is that I just don't think the
documentation can do this situation justice and that, as illustrated by
this thread, there are better resources available for these less common
situations.

That said adding something akin to your diagram and showing how the
different parts relate to each other is definitely worth considering -
though probably in the main section, not the reference section.

David J.