mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: improve description of dump/restore's --clean and --if-exists.

Browse Source 
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
This commit is contained in:
Tom Lane 2023-09-29 13:13:54 -04:00
parent ccd42ca046
commit 75af0f401f
3 changed files with 32 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/src/sgml/ref/pg_dump.sgml
View File

@ -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>
@ -839,9 +840,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>

17
doc/src/sgml/ref/pg_dumpall.sgml
View File

@ -91,9 +91,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>
@ -324,9 +327,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>

18
doc/src/sgml/ref/pg_restore.sgml
View File

@ -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>
@ -580,9 +582,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>