Avoid too prominent use of "backup" on pg_dump man page
In Karen Jex's presentation today at pgconf.dev [0]https://www.pgevents.ca/events/pgconfdev2024/schedule/session/126-how-postgres-is-misused-and-abused-in-the-wild/ 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/
https://www.pgevents.ca/events/pgconfdev2024/schedule/session/126-how-postgres-is-misused-and-abused-in-the-wild/
Attachments:
0001-doc-Avoid-too-prominent-use-of-backup-on-pg_dump-man.patchtext/plain; charset=UTF-8; name=0001-doc-Avoid-too-prominent-use-of-backup-on-pg_dump-man.patchDownload+9-6
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.