database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

doc: Avoid too prominent use of "backup" on pg_dump man page

Browse Source 
Some 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."

This tones this down a little bit, by replacing most uses of "backup"
with "export" and adding a short note that pg_dump is not a
general-purpose backup tool.

Discussion: https://www.postgresql.org/message-id/flat/70b48475-7706-4268-990d-fd522b038d96%40eisentraut.org
This commit is contained in:
Peter Eisentraut 2024-07-31 07:57:47 +02:00
parent 73275f093f
commit 4f29394ea9
2 changed files with 9 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/src/sgml/ref/pg_dump.sgml
View File

@ -36,16 +36,20 @@ PostgreSQL documentation
<title>Description</title> <title>Description</title>
<para> <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 <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 <application>pg_dump</application> does not block other users
accessing the database (readers or writers). 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>
<para> <para>
<application>pg_dump</application> only dumps a single database. <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), common to all databases in a cluster (such as roles and tablespaces),
use <xref linkend="app-pg-dumpall"/>. use <xref linkend="app-pg-dumpall"/>.
</para> </para>
@ -76,7 +80,7 @@ PostgreSQL documentation
<application>pg_restore</application>, <application>pg_restore</application>,
<application>pg_dump</application> provides a flexible archival and <application>pg_dump</application> provides a flexible archival and
transfer mechanism. <application>pg_dump</application> can be used to 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 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 database are to be restored. The most flexible output file formats are
the <quote>custom</quote> format (<option>-Fc</option>) and the the <quote>custom</quote> format (<option>-Fc</option>) and the

2
doc/src/sgml/ref/pg_restore.sgml
View File

@ -781,7 +781,7 @@ PostgreSQL documentation
Require that each schema Require that each schema
(<option>-n</option>/<option>--schema</option>) and table (<option>-n</option>/<option>--schema</option>) and table
(<option>-t</option>/<option>--table</option>) qualifier match at (<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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>