Horton

Thread

Commits

  1. Improve pg_dump/pg_dumpall help synopses and terminology

  2. doc: Avoid too prominent use of "backup" on pg_dump man page

  1. pg_dump/pg_dumpall help synopses and terminology

    Peter Eisentraut <peter@eisentraut.org> — 2025-06-10T06:59:29Z

    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?

  2. Re: pg_dump/pg_dumpall help synopses and terminology

    Ashutosh Bapat <ashutosh.bapat.oss@gmail.com> — 2025-06-10T11:51:35Z

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

  3. Re: pg_dump/pg_dumpall help synopses and terminology

    Peter Eisentraut <peter@eisentraut.org> — 2025-06-17T07:32:27Z

    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.

  4. Re: pg_dump/pg_dumpall help synopses and terminology

    Peter Eisentraut <peter@eisentraut.org> — 2025-06-17T07:43:13Z

    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.

  5. Re: pg_dump/pg_dumpall help synopses and terminology

    Robert Treat <rob@xzilla.net> — 2025-06-18T20:57:55Z

    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

  6. Re: pg_dump/pg_dumpall help synopses and terminology

    Peter Eisentraut <peter@eisentraut.org> — 2025-06-19T12:10:41Z

    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.