pg_dump/pg_dumpall help synopses and terminology
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?
Hi Peter,
On Tue, Jun 10, 2025 at 12:29 PM Peter Eisentraut <peter@eisentraut.org>
wrote:
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 formatspg_restore - restore PostgreSQL databases from archives created by
pg_dump or pg_dumpall
Since we are using "a PostgreSQL database" and "a PostgreSQL cluster" with
pg_dump and pg_dumpall respectively, it makes sense to use the same wording
for pg_restore. Th description at [1]https://www.postgresql.org/docs/18/app-pgrestore.html already does that, except it needs
small tweaks like below:
pg_restore - restore a PostgreSQL database or a PostgreSQL cluster from an
archive created by
pg_dump or pg_dumpall respectively.
[1]: https://www.postgresql.org/docs/18/app-pgrestore.html
--
Best Wishes,
Ashutosh Bapat
On 10.06.25 13:51, Ashutosh Bapat wrote:
Since we are using "a PostgreSQL database" and "a PostgreSQL cluster"
with pg_dump and pg_dumpall respectively, it makes sense to use the same
wording for pg_restore. Th description at [1] already does that, except
it needs small tweaks like below:pg_restore - restore a PostgreSQL database or a PostgreSQL cluster from
an archive created by
pg_dump or pg_dumpall respectively.[1] https://www.postgresql.org/docs/18/app-pgrestore.html <https://
www.postgresql.org/docs/18/app-pgrestore.html>
I think this is too long and too complex for a synopsis.
I also don't think that the "respectively" aspect is correct like that.
You could use pg_restore to restore less than all of the archive, so you
could restore just one database from an archive created by pg_dumpall.
The proposed phrasing "restore PostgreSQL databases" leaves it open how
many databases you want to restore.
I think the most important thing for the pg_restore synopsis is that it
mentions the relationship with pg_dump and pg_dumpall. Once you see
that, and you have heard about pg_dump/pg_dumpall before, you should be
able to get the overall picture. The rest should go into the description.
On 10.06.25 08:59, Peter Eisentraut wrote:
The pg_dump and pg_dumpall help synopses could use some refinements.
Here is a concrete patch.
Attachments:
0001-Improve-pg_dump-pg_dumpall-help-synopses-and-termino.patchtext/plain; charset=UTF-8; name=0001-Improve-pg_dump-pg_dumpall-help-synopses-and-termino.patchDownload+10-11
On Tue, Jun 17, 2025 at 3:32 AM Peter Eisentraut <peter@eisentraut.org> wrote:
On 10.06.25 13:51, Ashutosh Bapat wrote:
Since we are using "a PostgreSQL database" and "a PostgreSQL cluster"
with pg_dump and pg_dumpall respectively, it makes sense to use the same
wording for pg_restore. Th description at [1] already does that, except
it needs small tweaks like below:pg_restore - restore a PostgreSQL database or a PostgreSQL cluster from
an archive created by
pg_dump or pg_dumpall respectively.[1] https://www.postgresql.org/docs/18/app-pgrestore.html <https://
www.postgresql.org/docs/18/app-pgrestore.html>I think this is too long and too complex for a synopsis.
Definitely
I also don't think that the "respectively" aspect is correct like that.
You could use pg_restore to restore less than all of the archive, so you
could restore just one database from an archive created by pg_dumpall.The proposed phrasing "restore PostgreSQL databases" leaves it open how
many databases you want to restore.
Agreed
I think the most important thing for the pg_restore synopsis is that it
mentions the relationship with pg_dump and pg_dumpall. Once you see
that, and you have heard about pg_dump/pg_dumpall before, you should be
able to get the overall picture. The rest should go into the description.
+1
Looking at the patch, I sort of like the "specified format" language,
for example here and other various places:
- extract a <productname>PostgreSQL</productname> database into a
script file or other archive file
+ export a <productname>PostgreSQL</productname> database as an SQL
script or other specified format.I also wondered why you differentiated SQL script file vs archive in
the change here:
- of a cluster into an archive. The archive contains
+ of a cluster into an SQL script file or an archive. The output containsbut then did not differentiate them here (I guess it should say SQL
script files or archives?)
<refpurpose>
- restore a <productname>PostgreSQL</productname> database or cluster
- from an archive created by <application>pg_dump</application> or
+ restore <productname>PostgreSQL</productname> databases from archives
+ created by <application>pg_dump</application> or
<application>pg_dumpall</application>
</refpurpose>I don't know if there is an official definition of an archive, but I
don't tend to think of a single script (like default pg_dumpall) as an
archive.
Granted, these are just minor tightening up at best; generally +1 to
the clean up as a whole.
Robert Treat
https://xzilla.net
On 18.06.25 22:57, Robert Treat wrote:
I also wondered why you differentiated SQL script file vs archive in
the change here:- of a cluster into an archive. The archive contains + of a cluster into an SQL script file or an archive. The output containsbut then did not differentiate them here (I guess it should say SQL
script files or archives?)<refpurpose> - restore a <productname>PostgreSQL</productname> database or cluster - from an archive created by <application>pg_dump</application> or + restore <productname>PostgreSQL</productname> databases from archives + created by <application>pg_dump</application> or <application>pg_dumpall</application> </refpurpose>
The second bit is from pg_restore, which does not restore SQL script
files, only archives.
I don't know if there is an official definition of an archive, but I
don't tend to think of a single script (like default pg_dumpall) as an
archive.
I agree.
Granted, these are just minor tightening up at best; generally +1 to
the clean up as a whole.
Committed. Thanks for taking a look.