Doc: warn that parallel pg_restore may fail if --no-schema was used.

If the archive file was made with --no-schema or related options
then it likely does not have enough dependency information to
ensure that parallel restore will choose a workable restore order.
Document this.

In passing, do some minor wordsmithing on new nearby text about
restoring from pg_dumpall archives.

Author: vaibhave postgres <postgresvaibhave@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAM_eQjzTLtt1X9WKvMV6Rew0UvxT3mmhimZa9WT-vqaPjmXk-g@mail.gmail.com

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 7f538e9019483837a9151cd7f40129c81d015657..ae1bc14d2f26fbe5a9a53418c4678507037380b8 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1687,6 +1687,18 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    catalogs might be left in the wrong state.
   </para>
 
+  <para>
+   When creating an archive (non-text) output file, it is advisable not to
+   restrict the set of database objects dumped, but instead plan to apply
+   any desired object filtering when reading the archive
+   with <application>pg_restore</application>.  This will preserve
+   flexibility and possibly avoid problems at restore time; for details
+   see the <xref linkend="app-pgrestore"/> documentation.
+   In particular, dumping table data without the corresponding table
+   definition (via <option>--no-schema</option> and related options) is
+   not recommended.
+  </para>
+
   <para>
    When <option>--statistics</option> is specified,
    <command>pg_dump</command> will include most optimizer statistics in the

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 9d91c365214ec420da351858fc71baab30a6fd20..6ae2cdcfc10cd865600b9704e0644f48cad288f4 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1215,6 +1215,22 @@ CREATE DATABASE foo WITH TEMPLATE template0;
      </para>
     </listitem>
 
+    <listitem>
+     <para>
+      Parallel restore (<option>--jobs</option> greater than 1) requires
+      applying dependency information from the archive file to ensure
+      that an object is not restored before other objects it depends on.
+      This information will be incomplete, leading to unexpected restore
+      failures, if the archive does not include object definitions
+      (the <option>pre-data</option> section).  Therefore, avoid
+      using <application>pg_dump</application> options such
+      as <option>--no-schema</option>, <option>-a/--data-only</option>,
+      or <option>--section</option> without <option>pre-data</option> when
+      creating an archive you wish to restore in parallel.  Instead, you
+      may provide such options to <application>pg_restore</application>.
+     </para>
+    </listitem>
+
     <listitem>
      <para><application>pg_restore</application> cannot restore large objects
       selectively;  for instance, only those for a specific table.  If
@@ -1224,14 +1240,6 @@ CREATE DATABASE foo WITH TEMPLATE template0;
      </para>
     </listitem>
 
-    <listitem>
-     <para>
-      When restoring from a non-plain-text archive made using
-      <application>pg_dumpall</application>, the <option>--section</option>
-      option may be used, but must include <option>pre-data</option>.
-     </para>
-    </listitem>
-
     <listitem>
      <para>
       The following options cannot be used when restoring from a non-plain-text
@@ -1242,6 +1250,8 @@ CREATE DATABASE foo WITH TEMPLATE template0;
       <option>--no-schema</option>,
       <option>--statistics-only</option>, and
       <option>--strict-names</option>.
+      Also, if the <option>--section</option> option is used, it must
+      include <option>pre-data</option>.
      </para>
     </listitem>