Doc: improve description of dump/restore's --clean and --if-exists.

Try to make these option descriptions a little clearer for novices.
Per gripe from Attila Gulyás.

Discussion: https://postgr.es/m/169590536647.3727336.11070254203649648453@wrigleys.postgresql.org

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 374bca66a0ac0acc729d0b2f5bbc3cfbbc6596fb..023d82b2ef2f08be18abb3252861ccad17acf31c 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -168,11 +168,12 @@ PostgreSQL documentation
       --clean
       
        
-        Output commands to clean (drop)
+        Output commands to DROP all the dumped
         database objects prior to outputting the commands for creating them.
-        (Unless --if-exists is also specified,
-        restore might generate some harmless error messages, if any objects
-        were not present in the destination database.)
+        This option is useful when the restore is to overwrite an existing
+        database.  If any of the objects do not exist in the destination
+        database, ignorable error messages will be reported during
+        restore, unless --if-exists is also specified.
        
 
        
@@ -764,9 +765,11 @@ PostgreSQL documentation
       --if-exists
       
        
-        Use conditional commands (i.e., add an IF EXISTS
-        clause) when cleaning database objects.  This option is not valid
-        unless --clean is also specified.
+        Use DROP ... IF EXISTS commands to drop objects
+        in --clean mode.  This suppresses does not
+        exist errors that might otherwise be reported.  This
+        option is not valid unless --clean is also
+        specified.
        
       
      

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index e57f119bad6bd54109aee8096cf1a7d59c693f3c..2f0f7b78bc53f674dbbeab64f838f49853ee3978 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -90,9 +90,12 @@ PostgreSQL documentation
       --clean
       
        
-        Include SQL commands to clean (drop) databases before
-        recreating them.  DROP commands for roles and
-        tablespaces are added as well.
+        Emit SQL commands to DROP all the dumped
+        databases, roles, and tablespaces before recreating them.
+        This option is useful when the restore is to overwrite an existing
+        cluster.  If any of the objects do not exist in the destination
+        cluster, ignorable error messages will be reported during
+        restore, unless --if-exists is also specified.
        
       
      
@@ -321,9 +324,11 @@ PostgreSQL documentation
       --if-exists
       
        
-        Use conditional commands (i.e., add an IF EXISTS
-        clause) to drop databases and other objects.  This option is not valid
-        unless --clean is also specified.
+        Use DROP ... IF EXISTS commands to drop objects
+        in --clean mode.  This suppresses does not
+        exist errors that might otherwise be reported.  This
+        option is not valid unless --clean is also
+        specified.
        
       
      

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 7249a5e8336f5460f4cd5ba0089802efcb710910..f8e7351b82b7c15c4535b92092a05174a6c36e41 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -111,10 +111,12 @@ PostgreSQL documentation
       --clean
       
        
-        Clean (drop) database objects before recreating them.
-        (Unless --if-exists is used,
-        this might generate some harmless error messages, if any objects
-        were not present in the destination database.)
+        Before restoring database objects, issue commands
+        to DROP all the objects that will be restored.
+        This option is useful for overwriting an existing database.
+        If any of the objects do not exist in the destination database,
+        ignorable error messages will be reported,
+        unless --if-exists is also specified.
        
       
      
@@ -575,9 +577,11 @@ PostgreSQL documentation
       --if-exists
       
        
-        Use conditional commands (i.e., add an IF EXISTS
-        clause) to drop database objects.  This option is not valid
-        unless --clean is also specified.
+        Use DROP ... IF EXISTS commands to drop objects
+        in --clean mode.  This suppresses does not
+        exist errors that might otherwise be reported.  This
+        option is not valid unless --clean is also
+        specified.