Improve documentation about pg_dump's --quote-all-identifiers switch.

Per bug #14152 from Alejandro Martínez.  Back-patch to all supported
branches.

Discussion: <20160520165824[email protected]>

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index eaeb9a787efacb68f19774127ac9e6794c4eb6c2..2c2a5cf8328c8501e599ca67e751ed8b80dd894d 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -792,9 +792,16 @@ PostgreSQL documentation
       --quote-all-identifiers
       
        
-        Force quoting of all identifiers.  This may be useful when dumping a
-        database for migration to a future version that may have introduced
-        additional keywords.
+        Force quoting of all identifiers.  This option is recommended when
+        dumping a database from a server whose PostgreSQL
+        major version is different from pg_dump's, or when
+        the output is intended to be loaded into a server of a different
+        major version.  By default, pg_dump quotes only
+        identifiers that are reserved words in its own major version.
+        This sometimes results in compatibility issues when dealing with
+        servers of other versions that may have slightly different sets
+        of reserved words.  Using --quote-all-identifiers prevents
+        such issues, at the price of a harder-to-read dump script.
        
       
      

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 5c6a101333fe5622e46eb4e457377b81c0af49e5..f7036407973def9a20f61654c0ad62ab3db5e1f2 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -367,9 +367,16 @@ PostgreSQL documentation
       --quote-all-identifiers
       
        
-        Force quoting of all identifiers.  This may be useful when dumping a
-        database for migration to a future version that may have introduced
-        additional keywords.
+        Force quoting of all identifiers.  This option is recommended when
+        dumping a database from a server whose PostgreSQL
+        major version is different from pg_dumpall's, or when
+        the output is intended to be loaded into a server of a different
+        major version.  By default, pg_dumpall quotes only
+        identifiers that are reserved words in its own major version.
+        This sometimes results in compatibility issues when dealing with
+        servers of other versions that may have slightly different sets
+        of reserved words.  Using --quote-all-identifiers prevents
+        such issues, at the price of a harder-to-read dump script.