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 a3cf0608f5b1475814e750d366d56fe2ab00327a..7ff5d04c73d408e46141cf9a42bca79dbccbf54b 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -170,11 +170,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.
        
 
        
@@ -839,9 +840,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 e219a79858e80408704e51dc347c401af1856490..d31585216c60d27f659634390b35c9aaea23632b 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -91,9 +91,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.
        
       
      
@@ -324,9 +327,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 47bd7dbda061413bb50a73aff5adfd1c6a3a0950..a81583191c117dc9a520b43de116a3ed2ccb7b98 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.
        
       
      
@@ -580,9 +582,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.