Re: Stale description for pg_basebackup

On 2021/04/22 11:19, Kyotaro Horiguchi wrote:
> At Thu, 22 Apr 2021 10:56:10 +0900, Fujii Masao <masao.fujii@oss.nttdata.com> wrote in
>>
>>
>> On 2021/04/22 9:25, Kyotaro Horiguchi wrote:
>>>> What about the following description?
>>>>
>>>> -------------------
>>>> When you are using -X none, if write activity on the primary is low,
>>>> pg_basebackup may need to wait a long time for all WAL files required
>>>> for
>>>> the backup to be archived. It may be useful to run pg_switch_wal
>>>> on the primary in order to trigger an immediate WAL file switch and
>>>> archiving.
>>>> -------------------
>>> Looks far better.
>>
>> Patch attached. I appended the following description to assist
>> users to understand why pg_basebackup may need wait a long time
>> when write activity is low on the primary.
>>
>> ------------------
>> pg_basebackup cannot force the standby to switch to
>> a new WAL file at the end of backup.
>> ------------------
> 
> I'm not sure which is the convention here, but I saw that some
> function names in the doc are followed by parentheses (ie
> pg_switch_wal()).

Either works for me. I didn't add "()" because I just used the same description
as that in func.sgml.

         it may be useful to run <function>pg_switch_wal</function> on the
         primary in order to trigger an immediate segment switch.)


> (prepended?) It seems a bit redundant but also a bit clearer. How
> about the following simplification?
> 
> - It may be useful to run pg_switch_wal on the primary in order to
> - trigger an immediate WAL file switch and archiving.
> + It may be useful to run pg_switch_wal() on the primary in that case.

IMO "in order to..." part is helpful for us to understand why pg_switch_wal
is useful in this case. So I'd like to leave it.

Regards,

-- 
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION