Missing information on '-X' in section 26.3.6.1.

On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <noreply@postgresql.org>
wrote:

The following documentation comment has been logged on the website:

Page: 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.

David J.

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&gt;
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.
--
Daniel Gustafsson

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&gt;

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.

David J.

On Fri, Feb 2, 2024 at 12:41 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

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.

Created a new -hackers thread for my patch and added it to the commitfest
for July.

/messages/by-id/CAKFQuwaS6DtSde4TWpk133mfaQbgh8d+Pkk0kDN=6jf6qEWbvQ@mail.gmail.com

David J.