pg_dump.sgml

postgresql8.3.4源码,开源数据库

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.98.2.2 2008/08/26 00:03:24 tgl Exp $
PostgreSQL documentation
-->

<refentry id="APP-PGDUMP">
 <refmeta>
  <refentrytitle>pg_dump</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_dump</refname>

  <refpurpose>
   extract a <productname>PostgreSQL</productname> database into a script file or other archive file
  </refpurpose>
 </refnamediv>

 <indexterm zone="app-pgdump">
  <primary>pg_dump</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_dump</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg><replaceable>dbname</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="pg-dump-description">
  <title>
   Description
  </title>

  <para>
   <application>pg_dump</application> is a utility for backing up a
   <productname>PostgreSQL</productname> database. It makes consistent
   backups even if the database is being used concurrently.
   <application>pg_dump</application> does not block other users
   accessing the database (readers or writers).
  </para>

  <para>
   Dumps can be output in script or archive file formats. Script
   dumps are plain-text files containing the SQL commands required
   to reconstruct the database to the state it was in at the time it was
   saved. To restore from such a script, feed it to <xref
   linkend="app-psql">. Script files
   can be used to reconstruct the database even on other machines and
   other architectures; with some modifications even on other SQL
   database products.
  </para>

  <para>
   The alternative archive file formats must be used with
   <xref linkend="app-pgrestore"> to rebuild the database.  They
   allow <application>pg_restore</application> to be selective about
   what is restored, or even to reorder the items prior to being
   restored.
   The archive file formats are designed to be portable across
   architectures.
  </para>

  <para>
   When used with one of the archive file formats and combined with
   <application>pg_restore</application>,
   <application>pg_dump</application> provides a flexible archival and
   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. The <application>tar</application> format
   (<option>-Ft</option>) is not compressed and it is not possible to
   reorder data when loading, but it is otherwise quite flexible;
   moreover, it can be manipulated with standard Unix tools such as
   <command>tar</command>.
  </para>

  <para>
   While running <application>pg_dump</application>, one should examine the
   output for any warnings (printed on standard error), especially in
   light of the limitations listed below.
  </para>

 </refsect1>

 <refsect1 id="pg-dump-options">
  <title>Options</title>

  <para>
    The following command-line options control the content and
    format of the output.

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">dbname</replaceable></term>
      <listitem>
       <para>
        Specifies the name of the database to be dumped.  If this is
        not specified, the environment variable
        <envar>PGDATABASE</envar> is used.  If that is not set, the
        user name specified for the connection is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-a</></term>
      <term><option>--data-only</></term>
      <listitem>
       <para>
        Dump only the data, not the schema (data definitions).
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-b</></term>
      <term><option>--blobs</></term>
      <listitem>
       <para>
        Include large objects in the dump.  This is the default behavior
        except when <option>--schema</>, <option>--table</>, or
        <option>--schema-only</> is specified, so the <option>-b</>
        switch is only useful to add large objects to selective dumps.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c</option></term>
      <term><option>--clean</option></term>
      <listitem>
       <para>
        Output commands to clean (drop)
        database objects prior to (the commands for) creating them.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-C</></term>
      <term><option>--create</></term>
      <listitem>
       <para>
        Begin the output with a command to create the
        database itself and reconnect to the created database.  (With a
        script of this form, it doesn't matter which database you connect
        to before running the script.)
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d</option></term>
      <term><option>--inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands (rather
        than <command>COPY</command>).  This will make restoration very slow;
        it is mainly useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        Also, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
        Note that
        the restore might fail altogether if you have rearranged column order.
        The <option>-D</option> option is safe against column order changes,
        though even slower.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D</option></term>
      <term><option>--column-inserts</option></term>
      <term><option>--attribute-inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands with explicit
        column names (<literal>INSERT INTO
        <replaceable>table</replaceable>
        (<replaceable>column</replaceable>, ...) VALUES
        ...</literal>).  This will make restoration very slow; it is mainly
        useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        Also, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
      <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
      <listitem>
       <para>
        Create the dump in the specified character set encoding. By default,
        the dump is created in the database encoding.  (Another way to get the
        same result is to set the <envar>PGCLIENTENCODING</envar> environment
        variable to the desired dump encoding.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-f <replaceable class="parameter">file</replaceable></option></term>
      <term><option>--file=<replaceable class="parameter">file</replaceable></option></term>
      <listitem>
       <para>
        Send output to the specified file.  If this is omitted, the
        standard output is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
      <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
      <listitem>
       <para>
        Selects the format of the output.
        <replaceable>format</replaceable> can be one of the following:

       <variablelist>
        <varlistentry>
         <term><literal>p</></term>
         <term><literal>plain</></term>
         <listitem>
          <para>
           Output a plain-text <acronym>SQL</acronym> script file (the default).
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>c</></term>
         <term><literal>custom</></term>
         <listitem>
          <para>
           Output a custom archive suitable for input into
           <application>pg_restore</application>. This is the most flexible
           format in that it allows reordering of loading data as well
           as object definitions. This format is also compressed by default.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>t</></term>
         <term><literal>tar</></term>
         <listitem>
          <para>
           Output a <command>tar</command> archive suitable for input into
           <application>pg_restore</application>. Using this archive format
           allows reordering and/or exclusion of database objects
           at the time the database is restored. It is also possible to limit
           which data is reloaded at restore time.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>
       </para>

      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</></term>
      <term><option>--ignore-version</></term>
      <listitem>