PostgreSQL 12: Cryptic documentation
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/app-pgbasebackup.html
Description:
The pg_basebackup page says that the --waldir parameter "Specifies the
location for the write-ahead log directory. waldir must be an absolute path.
The write-ahead log directory can only be specified when the backup is in
plain mode." But it says nothing at all about what it is actually used
for.
You may think it is obvious. And I thought I could guess - it would be the
directory containing the WAL files for the database, right? But my attempt
to use it was met with "error: directory "/var/lib/pgsql/Walfiles" exists
but is not empty". But WAL files are part of the normal operation of the
database, aren't they? And so the directory _must_ exist, and it is not
surprising it has got something in it! But that seems to be a problem.
Which makes me realise I must have been completely wrong and I have no idea
what it for.
On Sat, Aug 15, 2020 at 6:58 AM PG Doc comments form <noreply@postgresql.org>
wrote:
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/app-pgbasebackup.html
Description:The pg_basebackup page says that the --waldir parameter "Specifies the
location for the write-ahead log directory. waldir must be an absolute
path.
The write-ahead log directory can only be specified when the backup is in
plain mode." But it says nothing at all about what it is actually used
for.You may think it is obvious. And I thought I could guess - it would be the
directory containing the WAL files for the database, right?
It's not the directory "of" the write-ahead log directory (i.e., existing)
but the directory "for" the write-ahead log directory (i.e. in the
backup). All information about the database being backed up can be gleaned
from the connection the pg_basebackup makes to the server.
Which makes me realise I must have been completely wrong and I have no idea
what it for.
I believe its purpose is to allow the user to specify a different directory
for the necessary restoration WAL files to be placed in compared to the
working WAL directory that will be created under the pgdata directory.
As with most things there is always room for improvement. In this case,
though, I'm not seeing anything wrong with the direct wording provided.
The behavior of the program, and general context, means that the directory
must be one that is being created during the backup and WAL copied into
it. And the error message means that in the rare case that the users
mis-interprets it they will be told. And as in this case the mailing lists
are responsive to clearing up individual confusion should the need arise.
Adding here, and in other places, explicit documentation that "this
specifies a location in the backup" just makes the documentation more
verbose. Maybe in this case not enough to reject a proposed patch but
enough so that I at least don't have a desire to write one.
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
As with most things there is always room for improvement. In this case,
though, I'm not seeing anything wrong with the direct wording provided.
Also, it's under a heading that says "The following command-line options
control the location and format of the output", which ought to make it
clear that it's not about the source server's WAL dir. (Although I notice
that whoever added the --max-rate parameter didn't read that heading :-()
Still, I see that the main -D parameter is described as "Directory to
write the output to", which seems like a clearer phrasing, so I'm inclined
to similarly reword the description of --waldir.
A more direct criticism of the --waldir description is that it's not
stated what happens if you don't provide that argument.
I notice some shaky grammar and other minor annoyances in this page,
so I'm kind of inclined to make an editorial pass over the whole thing.
regards, tom lane