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

petere · petere · commit 4f29394ea941 · 2024-07-31T07:57:47.000+02:00
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
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
@@ -36,16 +36,20 @@ PostgreSQL documentation
   <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 @@ PostgreSQL documentation
    <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
@@ -781,7 +781,7 @@ PostgreSQL documentation
         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>
