Thread: 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?
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 contains but 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