Doc: recommend "psql -X" for restoring pg_dump scripts.

This practice avoids possible problems caused by non-default psql
options, such as disabling AUTOCOMMIT.

Author: Shinya Kato <[email protected]>
Reviewed-by: Robert Treat <[email protected]>
Discussion: https://postgr.es/m/[email protected]
Backpatch-through: 13

3 files changed, 36 insertions, 11 deletions

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index e4e4c56cf14..25b8904baf7 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -106,10 +106,10 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
 
    <para>
     Text files created by <application>pg_dump</application> are intended to
-    be read in by the <application>psql</application> program. The
-    general command form to restore a dump is
+    be read by the <application>psql</application> program using its default
+    settings. The general command form to restore a text dump is
 <synopsis>
-psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">dumpfile</replaceable>
+psql -X <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">dumpfile</replaceable>
 </synopsis>
     where <replaceable class="parameter">dumpfile</replaceable> is the
     file output by the <application>pg_dump</application> command. The database <replaceable
@@ -117,11 +117,17 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
     command, so you must create it yourself from <literal>template0</literal>
     before executing <application>psql</application> (e.g., with
     <literal>createdb -T template0 <replaceable
-    class="parameter">dbname</replaceable></literal>).  <application>psql</application>
+    class="parameter">dbname</replaceable></literal>).
+    To ensure <application>psql</application> runs with its default settings,
+    use the <option>-X</option> (<option>--no-psqlrc</option>) option.
+    <application>psql</application>
     supports options similar to <application>pg_dump</application> for specifying
     the database server to connect to and the user name to use. See
     the <xref linkend="app-psql"/> reference page for more information.
-    Non-text file dumps are restored using the <xref
+   </para>
+
+   <para>
+    Non-text file dumps should be restored using the <xref
     linkend="app-pgrestore"/> utility.
    </para>
 
@@ -141,7 +147,7 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
     behavior and have <application>psql</application> exit with an
     exit status of 3 if an SQL error occurs:
 <programlisting>
-psql --set ON_ERROR_STOP=on <replaceable>dbname</replaceable> &lt; <replaceable>dumpfile</replaceable>
+psql -X --set ON_ERROR_STOP=on <replaceable>dbname</replaceable> &lt; <replaceable>dumpfile</replaceable>
 </programlisting>
     Either way, you will only have a partially restored database.
     Alternatively, you can specify that the whole dump should be
@@ -160,7 +166,7 @@ psql --set ON_ERROR_STOP=on <replaceable>dbname</replaceable> &lt; <replaceable>
     write to or read from pipes makes it possible to dump a database
     directly from one server to another, for example:
 <programlisting>
-pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> | psql -h <replaceable>host2</replaceable> <replaceable>dbname</replaceable>
+pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> | psql -X -h <replaceable>host2</replaceable> <replaceable>dbname</replaceable>
 </programlisting>
    </para>
 
@@ -205,7 +211,7 @@ pg_dumpall &gt; <replaceable>dumpfile</replaceable>
 </synopsis>
     The resulting dump can be restored with <application>psql</application>:
 <synopsis>
-psql -f <replaceable class="parameter">dumpfile</replaceable> postgres
+psql -X -f <replaceable class="parameter">dumpfile</replaceable> postgres
 </synopsis>
     (Actually, you can specify any existing database name to start from,
     but if you are loading into an empty cluster then <literal>postgres</literal>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index f27f2987bab..cfc74ca6d69 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1632,6 +1632,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    option will be automatically enabled by the subscriber if the subscription
    had been originally created with <literal>two_phase = true</literal> option.
   </para>
+
+  <para>
+   It is generally recommended to use the <option>-X</option>
+   (<option>--no-psqlrc</option>) option when restoring a database from a
+   plain-text <application>pg_dump</application> script to ensure a clean
+   restore process and prevent potential conflicts with
+   non-default <application>psql</application> configurations.
+  </para>
  </refsect1>
 
  <refsect1 id="pg-dump-examples" xreflabel="Examples">
@@ -1649,7 +1657,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    <literal>newdb</literal>:
 
 <screen>
-<prompt>$</prompt> <userinput>psql -d newdb -f db.sql</userinput>
+<prompt>$</prompt> <userinput>psql -X -d newdb -f db.sql</userinput>
 </screen>
   </para>
 
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 4d7c0464687..9624144c1f4 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -817,6 +817,17 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
    database creation will fail for databases in non-default
    locations.
   </para>
+
+  <para>
+   It is generally recommended to use the <option>-X</option>
+   (<option>--no-psqlrc</option>) option when restoring a database from a
+   <application>pg_dumpall</application> script to ensure a clean restore
+   process and prevent potential conflicts with non-default
+   <application>psql</application> configurations. Additionally, because
+   the <application>pg_dumpall</application> script may
+   include <application>psql</application> meta-commands, it may be
+   incompatible with clients other than <application>psql</application>.
+  </para>
  </refsect1>
 
 
@@ -833,9 +844,9 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
   <para>
    To restore database(s) from this file, you can use:
 <screen>
-<prompt>$</prompt> <userinput>psql -f db.out postgres</userinput>
+<prompt>$</prompt> <userinput>psql -X -f db.out -d postgres</userinput>
 </screen>
-   It is not important to which database you connect here since the
+   It is not important which database you connect to here since the
    script file created by <application>pg_dumpall</application> will
    contain the appropriate commands to create and connect to the saved
    databases.  An exception is that if you specified <option>--clean</option>,