Thread: Avoid too prominent use of "backup" on pg_dump man page
In Karen Jex's presentation today at pgconf.dev [0] one of the examples given was that users inadvertently rely on pg_dump as their primary backup tool, when better solutions exist. The pg_dump man page is arguably misleading in that it starts with "pg_dump is a utility for backing up a PostgreSQL database." I suggest toning this down a little bit. In the attached patch, I have replaced most uses of "backup" with "export" and added a short note that pg_dump is not a general-purpose backup tool. Suggestions for word-smithing welcome. [0]: https://www.pgevents.ca/events/pgconfdev2024/schedule/session/126-how-postgres-is-misused-and-abused-in-the-wild/
Attachment
> On 30 May 2024, at 01:11, Peter Eisentraut <peter@eisentraut.org> wrote: > Suggestions for word-smithing welcome. No objections to using export over backup, but it does make the use of "restore" feel awkward as that's generally an operation on a backup and not an export. - least one schema/table in the backup file. + least one schema/table in the file to be restored. Would it make sense to use "import" in some cases instead? -- Daniel Gustafsson
On Thu, 2024-05-30 at 08:21 +0200, Daniel Gustafsson wrote: > No objections to using export over backup, but it does make the use of > "restore" feel awkward as that's generally an operation on a backup and not an > export. > > - least one schema/table in the backup file. > + least one schema/table in the file to be restored. > > Would it make sense to use "import" in some cases instead? What about calling it "dump file" instead of "file to be restored"? Yours, Laurenz Albe
On 31.05.24 10:24, Laurenz Albe wrote: > On Thu, 2024-05-30 at 08:21 +0200, Daniel Gustafsson wrote: >> No objections to using export over backup, but it does make the use of >> "restore" feel awkward as that's generally an operation on a backup and not an >> export. >> >> - least one schema/table in the backup file. >> + least one schema/table in the file to be restored. >> >> Would it make sense to use "import" in some cases instead? > > What about calling it "dump file" instead of "file to be restored"? I forgot about this one for a bit. I committed it now as I had proposed it. The pg_restore man page consistently talks about "restoring" a file, so this change makes that more consistent. Introducing another verb would require more changes to properly introduce and explain it, which seems out of scope for this particular patch.