pg_dump_docs.diff

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index c4215be..ff5c8b7 100644
*** a/doc/src/sgml/backup.sgml
--- b/doc/src/sgml/backup.sgml
*************** pg_restore -d <replaceable class="parame
*** 310,315 ****
--- 310,334 ----
      with one of the other two approaches.
     </para>
  
+    <formalpara>
+     <title>Use <application>pg_dump</>'s parallel dump feature.</title>
+     <para>
+      To speed up the dump of a large database, you can use
+      <application>pg_dump</application>'s parallel mode. This will dump
+      multiple tables at the same time. You can control the degree of
+      parallelism with the <command>-j</command> parameter. Parallel dumps
+      are only supported for the "directory" archive mode.
+ 
+ <programlisting>
+ pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable class="parameter">out.dir</replaceable> <replaceable class="parameter">dbname</replaceable>
+ </programlisting>
+ 
+      You can use <command>pg_restore -j</command> to restore a dump in parallel.
+      This will work for any archive of either the "custom" or the "directory"
+      archive mode, no matter if it has been created with <command>pg_dump
+      -j</command> or not.
+     </para>
+    </formalpara>
    </sect2>
   </sect1>
  
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 1e7544a..34eace3 100644
*** a/doc/src/sgml/perform.sgml
--- b/doc/src/sgml/perform.sgml
*************** SELECT * FROM x, y, a, b, c WHERE someth
*** 1435,1440 ****
--- 1435,1449 ----
       </listitem>
       <listitem>
        <para>
+        Experiment with the parallel dump and restore modes of both
+        <application>pg_dump</> and <application>pg_restore</> and find the
+        optimal number of concurrent jobs to use. Dumping and restoring in
+        parallel by means of the <option>-j</> option should give you a
+        significantly higher performance over the serial mode.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
         Consider whether the whole dump should be restored as a single
         transaction.  To do that, pass the <option>-1</> or
         <option>--single-transaction</> command-line option to
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 152edcb..cb66205 100644
*** a/doc/src/sgml/ref/pg_dump.sgml
--- b/doc/src/sgml/ref/pg_dump.sgml
*************** PostgreSQL documentation
*** 73,82 ****
     transfer mechanism. <application>pg_dump</application> can be used to
     backup an entire database, then <application>pg_restore</application>
     can be used to examine the archive and/or select which parts of the
!    database are to be restored. The most flexible output file format is
!    the <quote>custom</quote> format (<option>-Fc</option>). It allows
!    for selection and reordering of all archived items, and is compressed
!    by default.
    </para>
  
    <para>
--- 73,84 ----
     transfer mechanism. <application>pg_dump</application> can be used to
     backup an entire database, then <application>pg_restore</application>
     can be used to examine the archive and/or select which parts of the
!    database are to be restored. The most flexible output file formats are
!    the <quote>custom</quote> format (<option>-Fc</option>) and the
!    <quote>directory</quote> format. They allow for selection and reordering
!    of all archived items, and are compressed by default. The
!    <quote>directory</quote> format is the only format that supports
!    parallel dumps.
    </para>
  
    <para>
*************** PostgreSQL documentation
*** 251,257 ****
             can read. A directory format archive can be manipulated with
             standard Unix tools; for example, files in an uncompressed archive
             can be compressed with the <application>gzip</application> tool.
!            This format is compressed by default.
            </para>
           </listitem>
          </varlistentry>
--- 253,260 ----
             can read. A directory format archive can be manipulated with
             standard Unix tools; for example, files in an uncompressed archive
             can be compressed with the <application>gzip</application> tool.
!            This format is compressed by default and also supports parallel
!            dumps.
            </para>
           </listitem>
          </varlistentry>
*************** PostgreSQL documentation
*** 286,291 ****
--- 289,350 ----
       </varlistentry>
  
       <varlistentry>
+       <term><option>-j <replaceable class="parameter">njobs</replaceable></></term>
+       <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></></term>
+       <listitem>
+        <para>
+         Run the dump in parallel by dumping <replaceable class="parameter">njobs</replaceable>
+         tables simultaneously. This option reduces the time of the dump but it also
+         increases the load on the database server. You can only use this option with the
+         directory output format because this is the only output format where multiple processes
+         can write their data at the same time.
+        </para>
+        <para>
+         <application>pg_dump</> will open <replaceable class="parameter">njobs</replaceable>
+         + 1 connections to the database, so make sure your <xref linkend="guc-max-connections">
+         setting is high enough to accommodate all connections.
+        </para>
+        <para>
+         Requesting exclusive locks on database objects while running a parallel dump could
+         cause the dump to fail. The reason is that the <application>pg_dump</> master process
+         requests shared locks on the objects that the worker processes are going to dump later
+         in order to
+         make sure that nobody deletes them and makes them go away while the dump is running.
+         Now if any other client requests an exclusive lock on a table, this lock will not be
+         granted but will queue after the shared lock of the master process. Consequently any
+         other access to the table will not be granted either and will queue after the exclusive
+         lock. This includes the worker process trying to dump the table. Without any
+         precautions this would be a classic deadlock situation. To detect this conflict, the
+         <application>pg_dump</> worker process requests another shared lock using the
+         <literal>NOWAIT</> option. If the worker process is not granted this shared lock,
+         this means that somebody else has requested an exclusive lock in the meantime and there
+         is no way to continue with the dump, so <application>pg_dump</> has no choice but to
+         abort the dump.
+        </para>
+        <para>
+         For a consistent backup, the database server needs to support synchronized snapshots,
+         a feature that was introduced in <productname>PostgreSQL</productname> 9.2. With this
+         feature, database clients can request to see the exact same dataset even though they
+         connected at different times. Technically, <command>pg_dump -j</command> uses several
+         regular database clients, it connects to the database once with the master process and
+         then once again for each worker job. Without the sychronized snapshot feature, the
+         different worker jobs wouldn't be guaranteed to see the same data from every worker
+         which could lead to an inconsistent backup.
+        </para>
+        <para>
+         If you want to run a parallel dump of a pre-9.2 server, you need to make sure that the
+         database content doesn't change from between the time the master connects to the
+         database until the last worker job has connected to the database. The easiest way to
+         do this is to halt any data modifying processes (DDL and DML) accessing the database
+         before starting the backup. You also need to specify the
+         <option>--no-synchronized-snapshots</option> parameter when running
+         <command>pg_dump -j</command> against a pre-9.2 <productname>PostgreSQL</productname>
+         server.
+        </para>
+       </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
        <term><option>-n <replaceable class="parameter">schema</replaceable></option></term>
        <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
        <listitem>
*************** PostgreSQL documentation
*** 691,696 ****
--- 750,766 ----
       </varlistentry>
  
       <varlistentry>
+       <term><option>--no-synchronized-snapshots</></term>
+       <listitem>
+        <para>
+         This option allows running <command>pg_dump -j</> against a pre-9.2
+         server, see the documentation of the <option>-j</option> parameter
+         for more details.
+        </para>
+       </listitem>
+      </varlistentry>
+ 
+      <varlistentry>
        <term><option>--no-tablespaces</option></term>
        <listitem>
         <para>
*************** CREATE DATABASE foo WITH TEMPLATE templa
*** 1062,1067 ****
--- 1132,1146 ----
  </screen>
    </para>
  
+   <para>
+    To dump a database into a directory-format archive in parallel with
+    5 worker jobs:
+ 
+ <screen>
+ <prompt>$</prompt> <userinput>pg_dump -Fd mydb -j 5 -f dumpdir</userinput>
+ </screen>
+   </para>
+ 
    <para>
     To reload an archive file into a (freshly created) database named
     <literal>newdb</>: