pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAvoid too prominent use of "backup" on pg_dump man page
4+ messages / 3 participants
[nested] [flat]
* Avoid too prominent use of "backup" on pg_dump man page
@ 2024-05-29 23:11 Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 4+ messages in thread
From: Peter Eisentraut @ 2024-05-29 23:11 UTC (permalink / raw)
To: pgsql-docs
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...
From dbf7c0785b9f2ddf85d19f3e41c22c72a600bb66 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Wed, 29 May 2024 16:01:26 -0700
Subject: [PATCH] doc: Avoid too prominent use of "backup" on pg_dump man page
---
doc/src/sgml/ref/pg_dump.sgml | 12 ++++++++----
doc/src/sgml/ref/pg_restore.sgml | 2 +-
2 files changed, 9 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 08d775379fd..af7949ee111 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -36,16 +36,20 @@
<title>Description</title>
<para>
- <application>pg_dump</application> is a utility for backing up a
+ <application>pg_dump</application> is a utility for exporting a
<productname>PostgreSQL</productname> database. It makes consistent
- backups even if the database is being used concurrently.
+ exports even if the database is being used concurrently.
<application>pg_dump</application> does not block other users
accessing the database (readers or writers).
+ Note, however, that except in simple cases,
+ <application>pg_dump</application> is generally not the right choice for
+ taking regular backups of production databases. See <xref
+ linkend="backup"/> for further discussion.
</para>
<para>
<application>pg_dump</application> only dumps a single database.
- To back up an entire cluster, or to back up global objects that are
+ To export an entire cluster, or to export global objects that are
common to all databases in a cluster (such as roles and tablespaces),
use <xref linkend="app-pg-dumpall"/>.
</para>
@@ -76,7 +80,7 @@ <title>Description</title>
<application>pg_restore</application>,
<application>pg_dump</application> provides a flexible archival and
transfer mechanism. <application>pg_dump</application> can be used to
- backup an entire database, then <application>pg_restore</application>
+ export an entire database, then <application>pg_restore</application>
can be used to examine the archive and/or select which parts of the
database are to be restored. The most flexible output file formats are
the <quote>custom</quote> format (<option>-Fc</option>) and the
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2e3ba802581..b8b27e1719e 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -781,7 +781,7 @@ <title>Options</title>
Require that each schema
(<option>-n</option>/<option>--schema</option>) and table
(<option>-t</option>/<option>--table</option>) qualifier match at
- least one schema/table in the backup file.
+ least one schema/table in the file to be restored.
</para>
</listitem>
</varlistentry>
--
2.45.1
Attachments:
[text/plain] 0001-doc-Avoid-too-prominent-use-of-backup-on-pg_dump-man.patch (2.8K, ../../70b48475-7706-4268-990d-fd522b038d96@eisentraut.org/2-0001-doc-Avoid-too-prominent-use-of-backup-on-pg_dump-man.patch)
download | inline diff:
From dbf7c0785b9f2ddf85d19f3e41c22c72a600bb66 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Wed, 29 May 2024 16:01:26 -0700
Subject: [PATCH] doc: Avoid too prominent use of "backup" on pg_dump man page
---
doc/src/sgml/ref/pg_dump.sgml | 12 ++++++++----
doc/src/sgml/ref/pg_restore.sgml | 2 +-
2 files changed, 9 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 08d775379fd..af7949ee111 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -36,16 +36,20 @@
<title>Description</title>
<para>
- <application>pg_dump</application> is a utility for backing up a
+ <application>pg_dump</application> is a utility for exporting a
<productname>PostgreSQL</productname> database. It makes consistent
- backups even if the database is being used concurrently.
+ exports even if the database is being used concurrently.
<application>pg_dump</application> does not block other users
accessing the database (readers or writers).
+ Note, however, that except in simple cases,
+ <application>pg_dump</application> is generally not the right choice for
+ taking regular backups of production databases. See <xref
+ linkend="backup"/> for further discussion.
</para>
<para>
<application>pg_dump</application> only dumps a single database.
- To back up an entire cluster, or to back up global objects that are
+ To export an entire cluster, or to export global objects that are
common to all databases in a cluster (such as roles and tablespaces),
use <xref linkend="app-pg-dumpall"/>.
</para>
@@ -76,7 +80,7 @@ <title>Description</title>
<application>pg_restore</application>,
<application>pg_dump</application> provides a flexible archival and
transfer mechanism. <application>pg_dump</application> can be used to
- backup an entire database, then <application>pg_restore</application>
+ export an entire database, then <application>pg_restore</application>
can be used to examine the archive and/or select which parts of the
database are to be restored. The most flexible output file formats are
the <quote>custom</quote> format (<option>-Fc</option>) and the
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2e3ba802581..b8b27e1719e 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -781,7 +781,7 @@ <title>Options</title>
Require that each schema
(<option>-n</option>/<option>--schema</option>) and table
(<option>-t</option>/<option>--table</option>) qualifier match at
- least one schema/table in the backup file.
+ least one schema/table in the file to be restored.
</para>
</listitem>
</varlistentry>
--
2.45.1
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Avoid too prominent use of "backup" on pg_dump man page
@ 2024-05-30 06:21 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2024-05-30 06:21 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: pgsql-docs
> 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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Avoid too prominent use of "backup" on pg_dump man page
@ 2024-05-31 08:24 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Laurenz Albe @ 2024-05-31 08:24 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Peter Eisentraut <peter@eisentraut.org>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Avoid too prominent use of "backup" on pg_dump man page
@ 2024-07-31 06:14 Peter Eisentraut <peter@eisentraut.org>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 0 replies; 4+ messages in thread
From: Peter Eisentraut @ 2024-07-31 06:14 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
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.
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2024-07-31 06:14 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-05-29 23:11 Avoid too prominent use of "backup" on pg_dump man page Peter Eisentraut <peter@eisentraut.org>
2024-05-30 06:21 ` Daniel Gustafsson <daniel@yesql.se>
2024-05-31 08:24 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-07-31 06:14 ` Peter Eisentraut <peter@eisentraut.org>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox