Thread

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