Docs: consolidate dependency notes in pg_dump and pg_restore

The pg_dump documentation had repetitive notes for the --schema,
--table, and --extension switches, noting that dependent database
objects are not automatically included in the dump.  This commit removes
these notes and replaces them with a consolidated paragraph in the
"Notes" section.

pg_restore had a similar note for -t but lacked one for -n; do likewise.

Also, add a note to --extension in pg_dump to note that ancillary files
(such as shared libraries and control files) are not included in the
dump and must be present on the destination system.

Author: Florents Tselai <florents.tselai@gmail.com>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/284C4D55-4F90-4AA0-84C8-1E6A28DDF271@gmail.com

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 688e23c0e908b396862b02e09eb76ee01be9ae7e..7f538e9019483837a9151cd7f40129c81d015657 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -263,12 +263,10 @@ PostgreSQL documentation
 
        <note>
         <para>
-         When <option>-e</option> is specified,
-         <application>pg_dump</application> makes no attempt to dump any other
-         database objects that the selected extension(s) might depend upon.
-         Therefore, there is no guarantee that the results of a
-         specific-extension dump can be successfully restored by themselves
-         into a clean database.
+         <application>pg_dump</application> does not dump the extension's
+         underlying installation files (such as shared libraries or control
+         files). These must be available on the destination system for the
+         restore to succeed.
         </para>
        </note>
       </listitem>
@@ -445,16 +443,6 @@ PostgreSQL documentation
         <xref linkend="pg-dump-examples"/> below.
        </para>
 
-       <note>
-        <para>
-         When <option>-n</option> is specified, <application>pg_dump</application>
-         makes no attempt to dump any other database objects that the selected
-         schema(s) might depend upon. Therefore, there is no guarantee
-         that the results of a specific-schema dump can be successfully
-         restored by themselves into a clean database.
-        </para>
-       </note>
-
        <note>
         <para>
          Non-schema objects such as large objects are not dumped when <option>-n</option> is
@@ -596,16 +584,6 @@ PostgreSQL documentation
         be dumped.
        </para>
 
-       <note>
-        <para>
-         When <option>-t</option> is specified, <application>pg_dump</application>
-         makes no attempt to dump any other database objects that the selected
-         table(s) might depend upon. Therefore, there is no guarantee
-         that the results of a specific-table dump can be successfully
-         restored by themselves into a clean database.
-        </para>
-       </note>
-
       </listitem>
      </varlistentry>
 
@@ -1689,6 +1667,17 @@ CREATE DATABASE foo WITH TEMPLATE template0;
 </programlisting>
   </para>
 
+  <para>
+   When options <option>-e</option>, <option>-n</option> or <option>-t</option>
+   are specified, <application>pg_dump</application> makes no attempt to dump
+   any other database objects that the selected object(s) might depend upon.
+   Therefore, there is no guarantee that the results of a dump so generated
+   can be successfully restored by themselves into a clean database.
+   For example, if a table whose definition includes a foreign key is
+   specified to be restored, the table referenced by the foreign key is
+   not automatically restored.
+  </para>
+
   <para>
    When a dump without schema is chosen and the option <option>--disable-triggers</option>
    is used, <application>pg_dump</application> emits commands

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2c295bbf8dc1c761377a33a5feb9ecb1867a513f..420a308a7c7d9bfcf63c0f69250e0b38fbd9853c 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -452,16 +452,6 @@ PostgreSQL documentation
         specify table(s) in a particular schema.
        </para>
 
-       <note>
-        <para>
-         When <option>-t</option> is specified, <application>pg_restore</application>
-         makes no attempt to restore any other database objects that the
-         selected table(s) might depend upon.  Therefore, there is no
-         guarantee that a specific-table restore into a clean database will
-         succeed.
-        </para>
-       </note>
-
        <note>
         <para>
          This flag does not behave identically to the <option>-t</option>
@@ -1089,6 +1079,16 @@ PostgreSQL documentation
  <refsect1 id="app-pgrestore-notes">
   <title>Notes</title>
 
+  <para>
+   When options <option>-n</option> or <option>-t</option> are specified,
+   <application>pg_restore</application> makes no attempt to restore
+   any other database objects that the selected table(s) or schema(s)
+   might depend upon.  Therefore, there is no guarantee that a specific-table
+   restore into a clean database will succeed.  For example, if a table
+   whose definition includes a foreign key is specified to be restored, the
+   table referenced by the foreign key is not automatically restored.
+  </para>
+
   <para>
    If your installation has any local additions to the
    <literal>template1</literal> database, be careful to load the output of