From: Tom Lane Date: Sat, 25 Jan 2025 17:42:05 +0000 (-0500) Subject: Doc: recommend "psql -X" for restoring pg_dump scripts. X-Git-Tag: REL_17_3~37 X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=76601c0c885aca203966d8f6f6d6683726a0823b;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 Reviewed-by: Robert Treat 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 e4e4c56cf14..25b8904baf7 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -106,10 +106,10 @@ pg_dump dbname > Text files created by pg_dump are intended to - be read in by the psql program. The - general command form to restore a dump is + be read by the psql program using its default + settings. The general command form to restore a text dump is -psql dbname < dumpfile +psql -X dbname < dumpfile where dumpfile is the file output by the pg_dump command. The database dbname < template0 before executing psql (e.g., with createdb -T template0 dbname). psql + class="parameter">dbname). + To ensure psql runs with its default settings, + use the () option. + psql supports options similar to pg_dump for specifying the database server to connect to and the user name to use. See the reference page for more information. - Non-text file dumps are restored using the + + + Non-text file dumps should be restored using the utility. @@ -141,7 +147,7 @@ psql dbname < psql exit with an exit status of 3 if an SQL error occurs: -psql --set ON_ERROR_STOP=on dbname < dumpfile +psql -X --set ON_ERROR_STOP=on dbname < dumpfile 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 dbname < write to or read from pipes makes it possible to dump a database directly from one server to another, for example: -pg_dump -h host1 dbname | psql -h host2 dbname +pg_dump -h host1 dbname | psql -X -h host2 dbname @@ -205,7 +211,7 @@ pg_dumpall > dumpfile The resulting dump can be restored with psql: -psql -f dumpfile postgres +psql -X -f dumpfile postgres (Actually, you can specify any existing database name to start from, but if you are loading into an empty cluster then postgres 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 two_phase = true option. + + + It is generally recommended to use the + () option when restoring a database from a + plain-text pg_dump script to ensure a clean + restore process and prevent potential conflicts with + non-default psql configurations. + @@ -1649,7 +1657,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; newdb: -$ psql -d newdb -f db.sql +$ psql -X -d newdb -f db.sql 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 PATTERN database creation will fail for databases in non-default locations. + + + It is generally recommended to use the + () option when restoring a database from a + pg_dumpall script to ensure a clean restore + process and prevent potential conflicts with non-default + psql configurations. Additionally, because + the pg_dumpall script may + include psql meta-commands, it may be + incompatible with clients other than psql. + @@ -833,9 +844,9 @@ exclude database PATTERN To restore database(s) from this file, you can use: -$ psql -f db.out postgres +$ psql -X -f db.out -d postgres - 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 pg_dumpall will contain the appropriate commands to create and connect to the saved databases. An exception is that if you specified ,