pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feeddoc bug for continuous archiving
4+ messages / 3 participants
[nested] [flat]
* doc bug for continuous archiving
@ 2020-10-07 21:34 Jeff Janes <jeff.janes@gmail.com>
2020-10-07 21:47 ` Re: doc bug for continuous archiving David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Jeff Janes @ 2020-10-07 21:34 UTC (permalink / raw)
To: pgsql-docs
Quoting the docs:
https://www.postgresql.org/docs/13/continuous-archiving.html
"As with base backups, the easiest way to produce a standalone hot backup
is to use the pg_basebackup tool. If you include the -X parameter when
calling it, all the write-ahead log required to use the backup will be
included in the backup automatically, and no special action is required to
restore the backup."
This makes it sound like -X is a switch option, when in fact it demands an
argument. The statement made is incorrect if the supplied argument is
"none", but is correct for the other two options. Should this be changed
to spell out which options it applies to (or maybe which option it does not
apply to).
I think this has been wrong ever since the capitalized -X was introduced in
9.2. Maybe it was intended to discuss -x, not -X ?
Cheers,
Jeff
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: doc bug for continuous archiving
2020-10-07 21:34 doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
@ 2020-10-07 21:47 ` David G. Johnston <david.g.johnston@gmail.com>
2020-10-07 22:12 ` Re: doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: David G. Johnston @ 2020-10-07 21:47 UTC (permalink / raw)
To: Jeff Janes <jeff.janes@gmail.com>; +Cc: pgsql-docs
On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes <jeff.janes@gmail.com> wrote:
> Quoting the docs:
>
> https://www.postgresql.org/docs/13/continuous-archiving.html
>
> "As with base backups, the easiest way to produce a standalone hot backup
> is to use the pg_basebackup tool. If you include the -X parameter when
> calling it, all the write-ahead log required to use the backup will be
> included in the backup automatically, and no special action is required to
> restore the backup."
>
> This makes it sound like -X is a switch option, when in fact it demands an
> argument. The statement made is incorrect if the supplied argument is
> "none", but is correct for the other two options. Should this be changed
> to spell out which options it applies to (or maybe which option it does not
> apply to).
>
Just reading the doc page for pg_basebackup: "stream" is the default method
value for this option. So if you just include "-X" you get "stream" which
is indeed a mode that just works and the continuous archiving section you
quote is correct.
I'm not really sure I like the idea that we don't indicate which
pg_basebackup key-value argument values are optional and which are
mandatory.
David J.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: doc bug for continuous archiving
2020-10-07 21:34 doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
2020-10-07 21:47 ` Re: doc bug for continuous archiving David G. Johnston <david.g.johnston@gmail.com>
@ 2020-10-07 22:12 ` Jeff Janes <jeff.janes@gmail.com>
2020-10-08 04:13 ` Re: doc bug for continuous archiving Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 1 reply; 4+ messages in thread
From: Jeff Janes @ 2020-10-07 22:12 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: pgsql-docs
On Wed, Oct 7, 2020 at 5:47 PM David G. Johnston <david.g.johnston@gmail.com>
wrote:
> On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes <jeff.janes@gmail.com> wrote:
>
>> Quoting the docs:
>>
>> https://www.postgresql.org/docs/13/continuous-archiving.html
>>
>> "As with base backups, the easiest way to produce a standalone hot backup
>> is to use the pg_basebackup tool. If you include the -X parameter when
>> calling it, all the write-ahead log required to use the backup will be
>> included in the backup automatically, and no special action is required to
>> restore the backup."
>>
>> This makes it sound like -X is a switch option, when in fact it demands
>> an argument. The statement made is incorrect if the supplied argument is
>> "none", but is correct for the other two options. Should this be changed
>> to spell out which options it applies to (or maybe which option it does not
>> apply to).
>>
>
> Just reading the doc page for pg_basebackup: "stream" is the default
> method value for this option. So if you just include "-X" you get "stream"
> which is indeed a mode that just works and the continuous archiving section
> you quote is correct.
>
> I'm not really sure I like the idea that we don't indicate which
> pg_basebackup key-value argument values are optional and which are
> mandatory.
>
> David J.
>
>
Stream is the default if you don't specify -X at all. If you specify -X
but with no argument for it, you get an error.
pg_basebackup: option requires an argument -- 'X'
Try "pg_basebackup --help" for more information.
(Which is also a bit confusing, I would expect a default to apply when the
option is specified without an argument, as opposed to when the
option itself it is not specified )
Cheers,
Jeff
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: doc bug for continuous archiving
2020-10-07 21:34 doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
2020-10-07 21:47 ` Re: doc bug for continuous archiving David G. Johnston <david.g.johnston@gmail.com>
2020-10-07 22:12 ` Re: doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
@ 2020-10-08 04:13 ` Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 0 replies; 4+ messages in thread
From: Fujii Masao @ 2020-10-08 04:13 UTC (permalink / raw)
To: Jeff Janes <jeff.janes@gmail.com>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: pgsql-docs
On 2020/10/08 7:12, Jeff Janes wrote:
> On Wed, Oct 7, 2020 at 5:47 PM David G. Johnston <david.g.johnston@gmail.com <mailto:david.g.johnston@gmail.com>> wrote:
>
> On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes <jeff.janes@gmail.com <mailto:jeff.janes@gmail.com>> wrote:
>
> Quoting the docs:
>
> https://www.postgresql.org/docs/13/continuous-archiving.html
>
> "As with base backups, the easiest way to produce a standalone hot backup is to use the pg_basebackup tool. If you include the -X parameter when calling it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is required to restore the backup."
>
> This makes it sound like -X is a switch option, when in fact it demands an argument. The statement made is incorrect if the supplied argument is "none", but is correct for the other two options. Should this be changed to spell out which options it applies to (or maybe which option it does not apply to).
>
>
> Just reading the doc page for pg_basebackup: "stream" is the default method value for this option. So if you just include "-X" you get "stream" which is indeed a mode that just works and the continuous archiving section you quote is correct.
>
> I'm not really sure I like the idea that we don't indicate which pg_basebackup key-value argument values are optional and which are mandatory.
>
> David J.
>
> Stream is the default if you don't specify -X at all.
We should use the description like "Unless -X none is specified when calling it" ?
> If you specify -X but with no argument for it, you get an error.
>
> pg_basebackup: option requires an argument -- 'X'
> Try "pg_basebackup --help" for more information.
>
> (Which is also a bit confusing, I would expect a default to apply when the option is specified without an argument, as opposed to when the option itself it is not specified )
As far as I recall, we discussed that in [1] and gave up doing that.
Regards,
[1]
https://postgr.es/m/1338235863.24935.27.camel@vanquo.pezone.net
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2020-10-08 04:13 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-10-07 21:34 doc bug for continuous archiving Jeff Janes <jeff.janes@gmail.com>
2020-10-07 21:47 ` David G. Johnston <david.g.johnston@gmail.com>
2020-10-07 22:12 ` Jeff Janes <jeff.janes@gmail.com>
2020-10-08 04:13 ` Fujii Masao <masao.fujii@oss.nttdata.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox