pg_dump/pg_dumpall help synopses and terminology

From: Peter Eisentraut <peter(at)eisentraut(dot)org>
To: pgsql-hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: pg_dump/pg_dumpall help synopses and terminology
Date: 2025-06-10 06:59:29
Message-ID: 3f71d8a7-095b-4829-9b0b-fce09e9866b3@eisentraut.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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?

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Jim Jones 2025-06-10 07:10:51 Re: Add XMLNamespaces to XMLElement
Previous Message Dilip Kumar 2025-06-10 06:44:52 Re: Question on error code selection in conflict detection