Thread: PostgreSQL 15 minor documentation improvements
Hello!
I’ve noticed that some changes concerning replacement of archive_command by archive_library in the documentation for PostgreSQL 15 do not quite fit in:
1. https://www.postgresql.org/docs/15/continuous-archiving.html
Archiving of these files happens automatically since you have already configured <varname>archive_library</varname>. - what about using archive_command? Should it be "...since you have already configured <varname>archive_library</varname> or <varname>archive_command</varname>"?
2. The same page.
If the archive process has fallen behind because of failures of the archive library, it will keep retrying until the archive succeeds and the backup is complete. - again, what about archive command?
3. https://www.postgresql.org/docs/15/app-pgbasebackup.html
All WAL records required for the backup must contain sufficient full-page writes, which requires you to enable full_page_writes on the primary and not to use a tool in your archive_library to remove full-page writes from WAL files. - the same question here. I believe that we can write in general: and not to use a tool to remove full-page writes from WAL files (?).
I have prepared a small patch with possible changes of these places, and also a separate patch with some improvements concerning missed/inapt tags. Please have a look.
Attachment
On Wed, Aug 17, 2022 at 06:09:13PM +0300, Максим Яблоков wrote:
> I have prepared a small patch with possible changes of these places, and
> also a separate patch with some improvements concerning missed/inapt tags.
> Please have a look.
archive_command is used only when archive_library is not set AFAIK,
but an archive_library could also freely use an archive_command if it
wishes to. But, yes, I agree that the current wording in backup.sgml
is kind of confusing because of this reason, so I am fine to have a
reference to both archive_library *and* archive_command in this area
of the docs.
All WAL records required for the backup must contain sufficient full-page writes,
which requires you to enable <varname>full_page_writes</varname> on the primary and
- not to use a tool in your <varname>archive_library</varname> to remove
- full-page writes from WAL files.
+ not to use a tool to remove full-page writes from WAL files.
Hmm. My opinion here is to do a simplification, and remove simply the
last part of the paragraph about tools that manipulate WAL files
as the first sentence makes it clear, in my opinion, that if those
FPWs are not around the server could become kaput.
Most of the changes in PGSQL15_tags_fix.patch seem right to me.
Still, you'd better check that the docs compile, as of:
> --- a/doc/src/sgml/basebackup-to-shell.sgml
> +++ b/doc/src/sgml/basebackup-to-shell.sgml
> @@ -12,9 +12,9 @@
> called <literal>shell</literal>. This makes it possible to run
> <literal>pg_basebackup --target=shell</literal> or, depending on how this
> module is configured,
> - <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause
> - a server command chosen by the server administrator to be executed for
> - each tar archive generated by the backup process. The command will receive
> + <literal>pg_basebackup --target=shell:<replaceable>DETAIL_STRING<replaceable></literal>,
I am pretty sure that this line is going to cause a compilation
failure of the docs. Anyway, this should be use a <command> markup,
no?
--
Michael
Attachment
Thanks, new patch is attached.I have prepared a small patch with possible changes of these places, and also a separate patch with some improvements concerning missed/inapt tags. Please have a look.archive_command is used only when archive_library is not set AFAIK, but an archive_library could also freely use an archive_command if it wishes to. But, yes, I agree that the current wording in backup.sgml is kind of confusing because of this reason, so I am fine to have a reference to both archive_library *and* archive_command in this area of the docs. All WAL records required for the backup must contain sufficient full-page writes, which requires you to enable <varname>full_page_writes</varname> on the primary and - not to use a tool in your <varname>archive_library</varname> to remove - full-page writes from WAL files. + not to use a tool to remove full-page writes from WAL files. Hmm. My opinion here is to do a simplification, and remove simply the last part of the paragraph about tools that manipulate WAL files as the first sentence makes it clear, in my opinion, that if those FPWs are not around the server could become kaput.
Yeah, sorry about that, I fixed it in the new patch.Most of the changes in PGSQL15_tags_fix.patch seem right to me. Still, you'd better check that the docs compile, as of:--- a/doc/src/sgml/basebackup-to-shell.sgml +++ b/doc/src/sgml/basebackup-to-shell.sgml @@ -12,9 +12,9 @@ called <literal>shell</literal>. This makes it possible to run <literal>pg_basebackup --target=shell</literal> or, depending on how this module is configured, - <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause - a server command chosen by the server administrator to be executed for - each tar archive generated by the backup process. The command will receive + <literal>pg_basebackup --target=shell:<replaceable>DETAIL_STRING<replaceable></literal>,I am pretty sure that this line is going to cause a compilation failure of the docs. Anyway, this should be use a <command> markup, no?
As for the <command> tag, it is written above:
<literal>pg_basebackup --target=shell</literal>
And also in backup.sgml there is the following:
<literal>createdb -T template0 <replaceable class="parameter">dbname</replaceable></literal>
So I believe that we can keep <literal> here.
Thanks a lot!
-- Michael
Attachment
On Thu, Aug 18, 2022 at 12:46:41PM +0300, Maxim Yablokov wrote: > Yeah, sorry about that, I fixed it in the new patch. > As for the <command> tag, it is written above: > <literal>pg_basebackup --target=shell</literal> > And also in backup.sgml there is the following: > <literal>createdb -T template0 <replaceable > class="parameter">dbname</replaceable></literal> > So I believe that we can keep <literal> here. Well, both are commands, but it is true that we use both patterns in the docs, still I have switched both to use <command>, and applied the patch after tweaking things a bit. (Note as well that the various SIG* use <literal> instead of <systemitem>, but I have not bothered about changing that). -- Michael