The pg_dump and pg_dumpall help synopses could use some refinements.
PG17:
pg_dump --help:
pg_dump dumps a database as a text file or to other formats.
pg_dumpall --help:
pg_dumpall extracts a PostgreSQL database cluster into an SQL script file.
man pages:
pg_dump - extract a PostgreSQL database into a script file or other
archive file
pg_dumpall - extract a PostgreSQL database cluster into a script file
Some criticisms here: 1) Inconsistent verbs "dumps"/"extracts". 2)
Inconsistent about "database" vs. "PostgreSQL database". 3)
Inconsistent about text file versus script file. 4) For the pg_dump
man page synopsis, it's questionable whether the directory format is an
"archive file", and whether "other archive file" should imply that a
script is also an archive file.
In PostgreSQL 18, pg_dumpall has gained the ability to dump to non-text
(non-script?) output formats, and the synopses have been rewritten to
account for that. Now they look like this:
pg_dump --help:
pg_dump dumps a database as a text file or to other formats.
pg_dumpall --help:
pg_dumpall extracts a PostgreSQL database cluster based on specified
dump format.
man pages:
pg_dump - extract a PostgreSQL database into a script file or other
archive file
pg_dumpall - extract a PostgreSQL database cluster using a specified
dump format
The point of the new pg_dumpall feature was to make pg_dump and
pg_dumpall more similar in capabilities, so I would also want the
descriptions to become more similar, not less. (Also, "based on
specified output format" sounds a bit odd.)
While we're here, let's also look at pg_restore:
pg_restore --help:
PG17: pg_restore restores a PostgreSQL database from an archive created
by pg_dump.
PG18: pg_restore restores PostgreSQL databases from archives created by
pg_dump or pg_dumpall.
man page:
PG17: pg_restore - restore a PostgreSQL database from an archive file
created by pg_dump
PG18: pg_restore - restore a PostgreSQL database or cluster from an
archive created by pg_dump or pg_dumpall
How about this to bring it all together:
pg_dump --help:
pg_dump exports a PostgreSQL database as an SQL script or to other formats.
pg_dumpall --help:
pg_dumpall exports a PostgreSQL database cluster as an SQL script or to
other formats.
(Note: Uses the verb "export", to align with commit 4f29394ea94.)
pg_restore --help: [unchanged]
pg_restore restores PostgreSQL databases from archives created by
pg_dump or pg_dumpall.
man pages:
pg_dump - export a PostgreSQL database as an SQL script or to other formats
pg_dumpall - export a PostgreSQL database cluster as an SQL script or to
other formats
pg_restore - restore PostgreSQL databases from archives created by
pg_dump or pg_dumpall
(Reworded to be more like --help output, to make it shorter.)
Thoughts?
