postgres.git / summary / log / commit / refs
commit f9cbff459061b80a56b440401670ce809dc395b9
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri Sep 29 17:13:54 2023 +0000
First released in: 17.0, 11.22, 12.17, 13.13, 14.10, 15.5, 16.1
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
doc/src/sgml/ref/pg_dump.sgml | 17 ++++++++++-------
doc/src/sgml/ref/pg_dumpall.sgml | 17 +++++++++++------
doc/src/sgml/ref/pg_restore.sgml | 18 +++++++++++-------
3 files changed, 32 insertions(+), 20 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 64940106538..97d8e7a593d 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -170,11 +170,12 @@ PostgreSQL documentation
<term><option>--clean</option></term>
<listitem>
<para>
- Output commands to clean (drop)
+ Output commands to <command>DROP</command> all the dumped
database objects prior to outputting the commands for creating them.
- (Unless <option>--if-exists</option> 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 <option>--if-exists</option> is also specified.
</para>
<para>
@@ -763,9 +764,11 @@ PostgreSQL documentation
<term><option>--if-exists</option></term>
<listitem>
<para>
- Use conditional commands (i.e., add an <literal>IF EXISTS</literal>
- clause) when cleaning database objects. This option is not valid
- unless <option>--clean</option> is also specified.
+ Use <literal>DROP ... IF EXISTS</literal> commands to drop objects
+ in <option>--clean</option> mode. This suppresses <quote>does not
+ exist</quote> errors that might otherwise be reported. This
+ option is not valid unless <option>--clean</option> is also
+ specified.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 3e6f87e502d..4f42ba66328 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -90,9 +90,12 @@ PostgreSQL documentation
<term><option>--clean</option></term>
<listitem>
<para>
- Include SQL commands to clean (drop) databases before
- recreating them. <command>DROP</command> commands for roles and
- tablespaces are added as well.
+ Emit SQL commands to <command>DROP</command> 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 <option>--if-exists</option> is also specified.
</para>
</listitem>
</varlistentry>
@@ -305,9 +308,11 @@ PostgreSQL documentation
<term><option>--if-exists</option></term>
<listitem>
<para>
- Use conditional commands (i.e., add an <literal>IF EXISTS</literal>
- clause) to drop databases and other objects. This option is not valid
- unless <option>--clean</option> is also specified.
+ Use <literal>DROP ... IF EXISTS</literal> commands to drop objects
+ in <option>--clean</option> mode. This suppresses <quote>does not
+ exist</quote> errors that might otherwise be reported. This
+ option is not valid unless <option>--clean</option> is also
+ specified.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index fbd2ffe7005..e8ee8df9bc1 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -111,10 +111,12 @@ PostgreSQL documentation
<term><option>--clean</option></term>
<listitem>
<para>
- Clean (drop) database objects before recreating them.
- (Unless <option>--if-exists</option> 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 <command>DROP</command> 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 <option>--if-exists</option> is also specified.
</para>
</listitem>
</varlistentry>
@@ -574,9 +576,11 @@ PostgreSQL documentation
<term><option>--if-exists</option></term>
<listitem>
<para>
- Use conditional commands (i.e., add an <literal>IF EXISTS</literal>
- clause) to drop database objects. This option is not valid
- unless <option>--clean</option> is also specified.
+ Use <literal>DROP ... IF EXISTS</literal> commands to drop objects
+ in <option>--clean</option> mode. This suppresses <quote>does not
+ exist</quote> errors that might otherwise be reported. This
+ option is not valid unless <option>--clean</option> is also
+ specified.
</para>
</listitem>
</varlistentry>
[parent: 750beed859f0]