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

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
index b95ed875176f7b1811d64b9654fd3cd058948feb..1010d817f18122fafe2184bfb96b4f1c58d89c1c 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -36,16 +36,20 @@ PostgreSQL documentation
   Description
 
   
-   pg_dump is a utility for backing up a
+   pg_dump is a utility for exporting a
    PostgreSQL database. It makes consistent
-   backups even if the database is being used concurrently.
+   exports even if the database is being used concurrently.
    pg_dump does not block other users
    accessing the database (readers or writers).
+   Note, however, that except in simple cases,
+   pg_dump is generally not the right choice for
+   taking regular backups of production databases.  See 
+   linkend="backup"/> for further discussion.
   
 
   
    pg_dump 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 .
   
@@ -76,7 +80,7 @@ PostgreSQL documentation
    pg_restore,
    pg_dump provides a flexible archival and
    transfer mechanism. pg_dump can be used to
-   backup an entire database, then pg_restore
+   export an entire database, then pg_restore
    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 custom format (-Fc) and the


diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml

index 2e3ba80258177a0abbe12346dd83d6701cbc8ae2..b8b27e1719ee72e1c9e8e1b4b2464f9ea662d88e 100644 (file)

--- 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
         (-n/--schema) and table
         (-t/--table) qualifier match at
-        least one schema/table in the backup file.
+        least one schema/table in the file to be restored.
        
       
      

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2e3ba80258177a0abbe12346dd83d6701cbc8ae2..b8b27e1719ee72e1c9e8e1b4b2464f9ea662d88e 100644 (file)
--- 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
         (-n/--schema) and table
         (-t/--table) qualifier match at
-        least one schema/table in the backup file.
+        least one schema/table in the file to be restored.