Doc: warn against using parallel restore with --load-via-partition-root.

This isn't terribly safe, and making it so doesn't seem like a small
project, so for the moment just warn against it.

Discussion: https://postgr.es/m/13624.1535486019@sss.pgh.pa.us

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 8286b2ddddaf6a4ad128f33427f6ff730b9aa277..790e81c32c917725b057009c3fb58132d6bf6b3c 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -793,13 +793,26 @@ PostgreSQL documentation
       --load-via-partition-root
       
        
-        When dumping a COPY or INSERT statement for a partitioned table,
-        target the root of the partitioning hierarchy which contains it rather
-        than the partition itself.  This may be useful when reloading data on
-        a server where rows do not always fall into the same partitions as
-        they did on the original server.  This could happen, for example, if
-        the partitioning column is of type text and the two system have
-        different definitions of the collation used to partition the data.
+        When dumping data for a table partition, make
+        the COPY or INSERT statements
+        target the root of the partitioning hierarchy that contains it, rather
+        than the partition itself.  This causes the appropriate partition to
+        be re-determined for each row when the data is loaded.  This may be
+        useful when reloading data on a server where rows do not always fall
+        into the same partitions as they did on the original server.  That
+        could happen, for example, if the partitioning column is of type text
+        and the two systems have different definitions of the collation used
+        to sort the partitioning column.
+       
+
+       
+        It is best not to use parallelism when restoring from an archive made
+        with this option, because pg_restore will
+        not know exactly which partition(s) a given archive data item will
+        load data into.  This could result in inefficiency due to lock
+        conflicts between parallel jobs, or perhaps even reload failures due
+        to foreign key constraints being set up before all the relevant data
+        is loaded.
        
       
      
@@ -915,7 +928,7 @@ PostgreSQL documentation
        
         Add ON CONFLICT DO NOTHING to
         INSERT commands.
-        This option is not valid unless --inserts or 
+        This option is not valid unless --inserts or
         --column-inserts is also specified.
        
       

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 94d76c30db3e305b652ea4cb7a25ca7b80b021bd..c51a130f43c5c31a9bbdf12b5ffaba6d1fd7562d 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -330,14 +330,21 @@ PostgreSQL documentation
       --load-via-partition-root
       
        
-        When dumping a COPY or INSERT statement for a partitioned table,
-        target the root of the partitioning hierarchy which contains it rather
-        than the partition itself.  This may be useful when reloading data on
-        a server where rows do not always fall into the same partitions as
-        they did on the original server.  This could happen, for example, if
-        the partitioning column is of type text and the two system have
-        different definitions of the collation used to partition the data.
+        When dumping data for a table partition, make
+        the COPY or INSERT statements
+        target the root of the partitioning hierarchy that contains it, rather
+        than the partition itself.  This causes the appropriate partition to
+        be re-determined for each row when the data is loaded.  This may be
+        useful when reloading data on a server where rows do not always fall
+        into the same partitions as they did on the original server.  That
+        could happen, for example, if the partitioning column is of type text
+        and the two systems have different definitions of the collation used
+        to sort the partitioning column.
        
+
+       
       
      
 
@@ -452,7 +459,7 @@ PostgreSQL documentation
        
         Add ON CONFLICT DO NOTHING to
         INSERT commands.
-        This option is not valid unless --inserts or 
+        This option is not valid unless --inserts or
         --column-inserts is also specified.