pg_dump/pg_dumpall help synopses and terminology

Started by Peter Eisentraut7 months ago6 messages

Peter Eisentraut

peter@eisentraut.org

7 months ago

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?

Ashutosh Bapat

ashutosh.bapat.oss@gmail.com

7 months ago

In reply to: Peter Eisentraut (#1)

Re: pg_dump/pg_dumpall help synopses and terminology

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 formats

pg_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

Peter Eisentraut

peter@eisentraut.org

7 months ago

In reply to: Ashutosh Bapat (#2)

Re: pg_dump/pg_dumpall help synopses and terminology

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.

Peter Eisentraut

peter@eisentraut.org

7 months ago

In reply to: Peter Eisentraut (#1)

1 attachment(s)

Re: pg_dump/pg_dumpall help synopses and terminology

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

From 3e92c4ef2502e2664478423f2bcd1fbf59b8e7fd Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 17 Jun 2025 09:39:17 +0200
Subject: [PATCH] Improve pg_dump/pg_dumpall help synopses and terminology

Increase consistency of --help and man page synopses between pg_dump
and pg_dumpall.  These should now be very similar, as pg_dumpall can
now also produce non-text dump output.  But actually, they have
drifted further apart.

- Use verb "export" consistently, instead of "dump" or "extract".
- Use "SQL script" instead of just "script" or "text file".
- Maintain consistent distinction between SQL script and other
  formats/archives (which is relevant for pg_restore).

Discussion: https://www.postgresql.org/message-id/flat/3f71d8a7-095b-4829-9b0b-fce09e9866b3%40eisentraut.org
---
 doc/src/sgml/ref/pg_dump.sgml    | 2 +-
 doc/src/sgml/ref/pg_dumpall.sgml | 7 +++++--
 doc/src/sgml/ref/pg_restore.sgml | 4 ++--
 src/bin/pg_dump/pg_dump.c        | 2 +-
 src/bin/pg_dump/pg_dumpall.c     | 2 +-
 5 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d7595a7e546..c95e3449367 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -18,7 +18,7 @@
   <refname>pg_dump</refname>
 
   <refpurpose>
-   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 to other formats
   </refpurpose>
  </refnamediv>
 
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 723a466cfaa..7281301c808 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -16,7 +16,10 @@
 
  <refnamediv>
   <refname>pg_dumpall</refname>
-  <refpurpose>extract a <productname>PostgreSQL</productname> database cluster using a specified dump format</refpurpose>
+
+  <refpurpose>
+   export a <productname>PostgreSQL</productname> database cluster as an SQL script or to other formats
+  </refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -33,7 +36,7 @@ <title>Description</title>
   <para>
    <application>pg_dumpall</application> is a utility for writing out
    (<quote>dumping</quote>) all <productname>PostgreSQL</productname> databases
-   of a cluster into an archive.  The archive contains
+   of a cluster into an SQL script file or an archive.  The output contains
    <acronym>SQL</acronym> commands that can be used as input to <xref
    linkend="app-psql"/> to restore the databases.  It does this by
    calling <xref linkend="app-pgdump"/> for each database in the cluster.
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 8c88b07dcc8..b649bd3a5ae 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -18,8 +18,8 @@
   <refname>pg_restore</refname>
 
   <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>
  </refnamediv>
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index 7bc0724cd30..11be05eab1c 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -1235,7 +1235,7 @@ main(int argc, char **argv)
 static void
 help(const char *progname)
 {
-	printf(_("%s dumps a database as a text file or to other formats.\n\n"), progname);
+	printf(_("%s exports a PostgreSQL database as an SQL script or to other formats.\n\n"), progname);
 	printf(_("Usage:\n"));
 	printf(_("  %s [OPTION]... [DBNAME]\n"), progname);
 
diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c
index b1f388cb391..3cbcad65c5f 100644
--- a/src/bin/pg_dump/pg_dumpall.c
+++ b/src/bin/pg_dump/pg_dumpall.c
@@ -699,7 +699,7 @@ main(int argc, char *argv[])
 static void
 help(void)
 {
-	printf(_("%s extracts a PostgreSQL database cluster based on specified dump format.\n\n"), progname);
+	printf(_("%s exports a PostgreSQL database cluster as an SQL script or to other formats.\n\n"), progname);
 	printf(_("Usage:\n"));
 	printf(_("  %s [OPTION]...\n"), progname);
 
-- 
2.49.0

Robert Treat

rob@xzilla.net

7 months ago

In reply to: Peter Eisentraut (#3)

Re: pg_dump/pg_dumpall help synopses and terminology

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.

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

Peter Eisentraut

peter@eisentraut.org

7 months ago

In reply to: Robert Treat (#5)

Re: pg_dump/pg_dumpall help synopses and terminology

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 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>

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.