Update for new pg_dump with blobs etc

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 1e5c70006da099b74822601aa2e76caa6e64b4d2..452cdbf253d5530ec224f412c08209af315a3d16 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.23 2000/11/13 23:57:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.24 2000/11/21 15:39:09 pjw Exp $
 Postgres documentation
 -->
 
@@ -15,26 +15,29 @@ Postgres documentation
    <application>pg_dump</application>
   </refname>
   <refpurpose>
-   Extract a <productname>Postgres</productname> database into a script file
+   Extract a <productname>Postgres</productname> database into a script file or other archive file 
   </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
-   <date>1999-07-20</date>
+   <date>2000-11-22</date>
   </refsynopsisdivinfo>
   <synopsis>
 pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
 pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
     [ -p <replaceable class="parameter">port</replaceable> ]
-    [ -t <replaceable class="parameter">table</replaceable> ]
-    [ -a ] [ -c ] [ -d ] [ -D ] [ -i ] [ -n ] [ -N ]
-    [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
+    [ -t <replaceable class="parameter">table</replaceable> ]\r
+    [ -a  ] [ -b ] [ -c  ] [-C] [ -d  ] [ -D  ] \r
+    [-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>] \r
+    [-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>] \r
+    [ -i  ] [ -n  ] [ -N  ] [ -o  ] [ -O ] [-R] \r
+    [ -s  ] [ -S ] [ -u  ] [ -v  ] [ -x ] [ -Z 0..9 ] \r
     [ <replaceable class="parameter">dbname</replaceable> ]
   </synopsis>
 
   <refsect2 id="R2-APP-PG-DUMP-1">
    <refsect2info>
-    <date>1998-11-05</date>
+    <date>2000-11-22</date>
    </refsect2info>
    <title>
     Inputs
@@ -66,20 +69,39 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term>-c</term>
-      <listitem>
-       <para>
-       Clean (drop) schema prior to create.
-       </para>
-      </listitem>
-     </varlistentry>
-
+     <varlistentry>\r
+      <term>-b</term>\r
+      <listitem>\r
+       <para>\r
+       Dump BLOB data.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-c</term>\r
+      <listitem>\r
+       <para>\r
+       Clean (drop) schema prior to create.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-C</term>\r
+      <listitem>\r
+       <para>\r
+       For plain text (script) output, include SQL to create the database itself.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
      <varlistentry>
       <term>-d</term>
       <listitem>
        <para>
-       Dump data as proper insert strings.
+       Dump data as proper insert strings. This is not recommended for large databases\r
+      for performance reasons.
        </para>
       </listitem>
      </varlistentry>
@@ -88,10 +110,68 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
       <term>-D</term>
       <listitem>
        <para>
-       Dump data as inserts with attribute names
+       Dump data as inserts with attribute names. This is not recommended for large databases\r
+      for performance reasons.
        </para>
       </listitem>
      </varlistentry>
+\r
+     <varlistentry>\r
+      <term>-f <replaceable class="parameter">file</replaceable></term>\r
+      <listitem>\r
+       <para>\r
+       Send output to the specified file.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-F <replaceable class="parameter">format</replaceable></term>\r
+      <listitem>\r
+       <para>\r
+       Format can be one of the following:\r
+       </para>\r
+\r
+\r
+       <variablelist>\r
+        <varlistentry>\r
+         <term>p</term>\r
+         <listitem>\r
+          <para>\r
+         output a plain text SQL script file (default)\r
+          </para>\r
+         </listitem>\r
+        </varlistentry>\r
+\r
+        <varlistentry>\r
+         <term>t</term>\r
+         <listitem>\r
+          <para>\r
+         output a TAR archive suitable for input into \r
+         <APPLICATION>pg_restore</APPLICATION>. Using this archive format \r
+         allows reordering and/or exclusion of schema elements \r
+         at the time the database is restored. It is also possible to limit \r
+         which data is reloaded at restore time.\r
+          </para>\r
+         </listitem>\r
+        </varlistentry>\r
+\r
+        <varlistentry>\r
+         <term>c</term>\r
+         <listitem>\r
+          <para>\r
+         output a custom archive suitable for input into \r
+         <APPLICATION>pg_restore</APPLICATION>. This is the most flexible \r
+         format in that it allows reordering of data load as well \r
+         as schema elements. This format is also compressed by default.\r
+          </para>\r
+         </listitem>\r
+        </varlistentry>\r
+\r
+       </variablelist>\r
+\r
+      </listitem>\r
+     </varlistentry>\r
 
      <varlistentry>
       <term>-i</term>
@@ -132,15 +212,37 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term>-o</term>
-      <listitem>
-       <para>
-       Dump object identifiers (<acronym>OID</acronym>s) for every table.
-       </para>
-      </listitem>
-     </varlistentry>
-
+     <varlistentry>\r
+      <term>-o</term>\r
+      <listitem>\r
+       <para>\r
+       Dump object identifiers (<acronym>OID</acronym>s) for every table.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-O</term>\r
+      <listitem>\r
+       <para>\r
+       In plain text output mode, don't set object ownership to match the \r
+      original database. Typically, <APPLICATION>pg_dump</APPLICATION> \r
+      issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set \r
+      ownership of schema elements.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-R</term>\r
+      <listitem>\r
+       <para>\r
+       In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION> \r
+      from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
      <varlistentry>
       <term>-s</term>
       <listitem>
@@ -150,15 +252,25 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term>-t <replaceable class="parameter">table</replaceable></term>
-      <listitem>
-       <para>
-       Dump data for <replaceable class="parameter">table</replaceable> only.
-       </para>
-      </listitem>
-     </varlistentry>
-
+     <varlistentry>\r
+      <term>-S <replaceable class="parameter">username</replaceable></term>\r
+      <listitem>\r
+       <para>\r
+       Specify the superuser username to use when disabling triggers and/or \r
+      setting ownership of schema elements.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
+     <varlistentry>\r
+      <term>-t <replaceable class="parameter">table</replaceable></term>\r
+      <listitem>\r
+       <para>\r
+       Dump data for <replaceable class="parameter">table</replaceable> only.\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
      <varlistentry>
       <term>-u</term>
       <listitem>
@@ -185,6 +297,17 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
        </para>
       </listitem>
      </varlistentry>
+\r
+     <varlistentry>\r
+      <term>-Z <replaceable class="parameter">0..9</replaceable></term>\r
+      <listitem>\r
+       <para>\r
+       Specify the compression level to use in archive formats that support \r
+      compression (currently only the custom archive format supports compression).\r
+       </para>\r
+      </listitem>\r
+     </varlistentry>\r
+\r
 
     </variablelist>
    </para>
@@ -306,17 +429,26 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
 
  <refsect1 id="R1-APP-PG-DUMP-1">
   <refsect1info>
-   <date>1998-11-05</date>
+   <date>2000-</date>
   </refsect1info>
   <title>
    Description
   </title>
   <para>
    <application>pg_dump</application> is a utility for dumping out a 
-   <productname>Postgres</productname> database into a script file
-   containing query commands.  The script
-   files are in text format and can be used to reconstruct the database,
-   even on other machines and other architectures.  
+   <productname>Postgres</productname> database into a script or archive \r
+   file containing query commands. The script files are in text format \r
+   and can be used to reconstruct the database, even on other machines \r
+   and other architectures.\r
+  </para>\r
+  <para> 
+   The archive files, new with this v7.1, contain enough information for \r
+   <APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also\r
+   allow pg_restore to be selective about what is restored, or even to \r
+   reorder the items prior to being restored. The archive files should \r
+   also be portable across architectures.\r
+  </para>\r
+  <para>\r
    <application>pg_dump</application> 
    will produce the queries necessary to re-generate all
    user-defined types, functions, tables, indices, aggregates, and
@@ -330,14 +462,28 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
    is useful for dumping out the contents of a database to move from one
    <productname>Postgres</productname> installation to another.  After running 
    <application>pg_dump</application>,
-   one should examine the output script file for any warnings, especially
+   one should examine the output for any warnings, especially
    in light of the limitations listed below. 
   </para>
+\r
+  <para>\r
+   When used with one of the alternate file formats and combined with \r
+   <APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival \r
+   and trasfer mechanism. <APPLICATION>pg_dump</APPLICATION> can be used \r
+   to backup an entire database, then <APPLICATION>pg_restore</APPLICATION> \r
+   can be used to examine the archive and/or select which parts of the \r
+   database are to be restored.\r
+  </para>\r
+\r
+  <para>\r
+   See the <APPLICATION>pg_restore</APPLICATION> documentation for details.\r
+  </para>\r
+\r
  </refsect1>
 
  <refsect1 id="R1-APP-PG-DUMP-2">
   <refsect1info>
-   <date>1998-11-05</date>
+   <date>2000-11-21</date>
   </refsect1info>
   <title>
    Notes
@@ -359,8 +505,9 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
 
     <listitem>
      <para>
-      <application>pg_dump</application> does not handle large objects.
-      Large objects are ignored and must be dealt with manually. 
+      When dumping a single table or as plain text, <application>pg_dump</application> \r
+      does not handle large objects. Large objects must be dumped in their\r
+      entirity using one of the binary archive formats.\r
      </para>
     </listitem>
 
@@ -379,7 +526,7 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
 
  <refsect1 id="R1-APP-PG-DUMP-3">
   <refsect1info>
-   <date>1998-11-05</date>
+   <date>2000-11-21</date>
   </refsect1info>
   <title>
    Usage
@@ -399,6 +546,23 @@ $ pg_dump > db.out
 $ psql -e database < db.out
    </programlisting>
   </para>
+\r
+  <para>\r
+   To dump a database called mydb that contains BLOBs to a TAR file:\r
+\r
+   <programlisting>\r
+$ pg_dump -Ft --blobs mydb > db.tar\r
+   </programlisting>\r
+  </para>\r
+\r
+  <para>\r
+   To reload this database (with BLOBs) to an existing db called newdb:\r
+\r
+   <programlisting>\r
+$ pg_restore db.tar --db=newdb\r
+   </programlisting>\r
+  </para>\r
+\r
  </refsect1>
 </refentry>