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
