On Wed, Jan 24, 2024 at 2:19 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> On 23 Jan 2024, at 21:43, David G. Johnston <david.g.johnston@gmail.com> wrote: > > On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <noreply@postgresql.org <mailto:noreply@postgresql.org>> wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/continuous-archiving.html <https://www.postgresql.org/docs/16/continuous-archiving.html> > Description: > > I noticed, that in section 26.3.6.1. it's not specified, what the -X > parameter should be set to (stream or fetch, or whether it even matters). I > could continue with trial and error, but it confused me a bit. > > The -X parameter is documented to have a default; but since both fetch and stream are documented to give you the same end result it doesn't matter. Of course you cannot specify the none method.
Agreed. Still, it doesn't hurt to spell out what we take for granted but a newcomer have to figure out in order to make the documentation easy to follow for new users. Something like the attached would be enough I think.
So I once again find a larger issue here, mostly unrelated to the complaint at hand.
This entire paragraph is in the Continuous Archiving & PITR section but the entire standalone concept is in opposition to that. It is also in a "Tips" section but doesn't really read as a tip.
Thinking on it further, and as the tip talks about, what we are really doing here is describing a standalone physical file system backup in contrast to a pg_dump backup. We already have a chapter that does this - the previous one named "File System Level Backup".
The attached patch moves this paragraph there. I distilled the paragraph down to its essence, but am open to being a bit more wordy, and consider more how this fits into the existing content of that page. I'm only really married to two things - mentioning the -X argument to pg_basebackup here is a bad idea and the content does not fit in the existing Tip area of continuous archiving section.