From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 25 Jan 2025 17:42:05 +0000 (-0500)
Subject: Doc: recommend "psql -X" for restoring pg_dump scripts.
X-Git-Tag: REL_14_16~23
X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=4106942f004fdd789ea4b35be0585c1f8268744d;p=postgresql.git
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 <Shinya11.Kato@oss.nttdata.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Discussion: https://postgr.es/m/96ff23a5d858ff72ca8e823a014d16fe@oss.nttdata.com
Backpatch-through: 13
---
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index cba32b6eb3e..e2030d6f48e 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -106,10 +106,10 @@ pg_dump <replaceable class="parameter">dbname</replaceable> > <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> < <replaceable class="parameter">dumpfile</replaceable>
+psql -X <replaceable class="parameter">dbname</replaceable> < <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> < <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> < <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> < <replaceable>dumpfile</replaceable>
+psql -X --set ON_ERROR_STOP=on <replaceable>dbname</replaceable> < <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> < <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 > <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 9ec8e6d202c..5e5c141e178 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1408,6 +1408,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
information might have to be changed. It might also be appropriate to
truncate the target tables before initiating a new full table copy.
</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">
@@ -1425,7 +1433,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 cb071903783..0d77a4836ae 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -774,6 +774,17 @@ PostgreSQL documentation
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>
@@ -790,9 +801,9 @@ PostgreSQL documentation
<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>,