Re: PG 16 draft release notes ready

On Thu, May 18, 2023 at 1:49 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> I will adjust it to the feedback I receive; that URL will quickly show
> all updates.
>
> I learned a few things creating it this time:
>
> * I can get confused over C function names and SQL function names in
> commit messages.

The commit history covering pg_walinspect was complicated. Some of the
newly added stuff was revised multiple times, by multiple authors due
to changing ideas about the best UI. Here is some concrete feedback
about that:

* Two functions that were in 15 that each end in *_till_end_of_wal()
were removed for 16, since the same functionality is now provided
through a more intuitive UI: we now tolerate invalid end_lsn values
"from the future", per a new "Tip" in the pg_walinspect documentation
for 16.

In my opinion this should (at most) be covered as a compatibility
item. It's not really new functionality.

* There is one truly new pg_walinspect function added to 16:
pg_get_wal_block_info(). Its main purpose is to see how each
individual block changed -- it's far easier to track how blocks
changed over time using the new function. The original "record
orientated" functions made that very difficult (regex hacks were
required).

pg_get_wal_block_info first appeared under another name, and had
somewhat narrower functionality to the final version, all of which
shouldn't matter to users -- since they never saw a stable release
with any of that. There is no point in telling users about the commits
that changed the name/functionality of pg_get_wal_block_info that came
only a couple of months after the earliest version was commited -- to
users, it is simply a new function with new functionality.

I also suggest merging the pg_waldump items with the section you've
added covering pg_walinspect. A "pg_walinspect and pg_waldump" section
seems natural to me. Some of the enhancements in this area benefit
pg_walinspect and pg_waldump in exactly the same way, since
pg_walinspect is essentially a backend/SQL interface equivalent of
pg_waldump's frontend/CLI interface. Melanie's work on improving the
descriptions output for WAL records like Heap's PRUNE and VACUUM
records is a great example of this -- it does exactly the same thing
for pg_walinspect and pg_waldump, without directly targeting either
(it also affects the wal_debug developer option).

It might also make sense to say that the enhanced WAL record
descriptions from Melanie generally apply to records used by VACUUM
only.

Note also that the item "Add pg_waldump option --save-fullpage to dump
full page images (David Christensen)" is tangentially related to
pg_get_wal_block_info(), since you can also get FPIs using
pg_get_wal_block_info() (in fact, that was originally its main
purpose). I'm not saying that you necessarily need to connect them
together in any way, but you might consider it.

--
Peter Geoghegan