Обсуждение: 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