pg_restore.sgml

postgresql8.3.4源码,开源数据库

      <term><option>-x</option></term>
      <term><option>--no-privileges</option></term>
      <term><option>--no-acl</option></term>
      <listitem>
       <para>
        Prevent restoration of access privileges (grant/revoke commands).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--disable-triggers</></term>
      <listitem>
       <para>
        This option is only relevant when performing a data-only restore.
        It instructs <application>pg_restore</application> to execute commands
        to temporarily disable triggers on the target tables while
        the data is reloaded.  Use this if you have referential
        integrity checks or other triggers on the tables that you
        do not want to invoke during data reload.
       </para>

       <para>
        Presently, the commands emitted for
        <option>--disable-triggers</> must be done as superuser.  So, you
        should also specify a superuser name with <option>-S</>, or
        preferably run <application>pg_restore</application> as a
        <productname>PostgreSQL</> superuser.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--use-set-session-authorization</option></term>
      <listitem>
       <para>
        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
        instead of <command>ALTER OWNER</> commands to determine object
        ownership.  This makes the dump more standards compatible, but
        depending on the history of the objects in the dump, might not restore
        properly.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--no-data-for-failed-tables</option></term>
      <listitem>
       <para>
        By default, table data is restored even if the creation command
        for the table failed (e.g., because it already exists).
        With this option, data for such a table is skipped.
        This behavior is useful if the target database already
        contains the desired table contents.  For example,
        auxiliary tables for <productname>PostgreSQL</> extensions
        such as <productname>PostGIS</> might already be loaded in
        the target database; specifying this option prevents duplicate
        or obsolete data from being loaded into them.
       </para>

       <para>
        This option is effective only when restoring directly into a
        database, not when producing SQL script output.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    <application>pg_restore</application> also accepts
    the following command line arguments for connection parameters:

    <variablelist>
     <varlistentry>
      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
      <listitem>
       <para>
        Specifies the host name of the machine on which the server is
        running.  If the value begins with a slash, it is used as the
        directory for the Unix domain socket. The default is taken
        from the <envar>PGHOST</envar> environment variable, if set,
        else a Unix domain socket connection is attempted.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
      <listitem>
       <para>
        Specifies the TCP port or local Unix domain socket file
        extension on which the server is listening for connections.
        Defaults to the <envar>PGPORT</envar> environment variable, if
        set, or a compiled-in default.
        </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-U <replaceable>username</replaceable></option></term>
      <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
      <listitem>
       <para>
        User name to connect as.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</option></term>
      <term><option>--password</option></term>
      <listitem>
       <para>
        Force <application>pg_restore</application> to prompt for a
        password before connecting to a database.  
       </para>

       <para>
        This option is never essential, since
        <application>pg_restore</application> will automatically prompt
        for a password if the server demands password authentication.
        However, <application>pg_restore</application> will waste a
        connection attempt finding out that the server wants a password.
        In some cases it is worth typing <option>-W</> to avoid the extra
        connection attempt.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-1</option></term>
      <term><option>--single-transaction</option></term>
      <listitem>
       <para>
        Execute the restore as a single transaction (that is, wrap the
        emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
        ensures that either all the commands complete successfully, or no
        changes are applied. This option implies
        <option>--exit-on-error</>.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGHOST</envar></term>
    <term><envar>PGPORT</envar></term>
    <term><envar>PGUSER</envar></term>

    <listitem>
     <para>
      Default connection parameters
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   This utility, like most other <productname>PostgreSQL</> utilities,
   also uses the environment variables supported by <application>libpq</>
   (see <xref linkend="libpq-envars">).
  </para>

 </refsect1>


 <refsect1 id="app-pgrestore-diagnostics">
  <title>Diagnostics</title>

  <para>
   When a direct database connection is specified using the
   <option>-d</option> option, <application>pg_restore</application>
   internally executes <acronym>SQL</acronym> statements. If you have
   problems running <application>pg_restore</application>, make sure
   you are able to select information from the database using, for
   example, <xref linkend="app-psql">.  Also, any default connection
   settings and environment variables used by the
   <application>libpq</application> front-end library will apply.
  </para>
 </refsect1>


 <refsect1 id="app-pgrestore-notes">
  <title>Notes</title>

  <para>
   If your installation has any local additions to the
   <literal>template1</> database, be careful to load the output of
   <application>pg_restore</application> into a truly empty database;
   otherwise you are likely to get errors due to duplicate definitions
   of the added objects.  To make an empty database without any local
   additions, copy from <literal>template0</> not <literal>template1</>, for example:
<programlisting>
CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting>
  </para>

  <para>
   The limitations of <application>pg_restore</application> are detailed below.

   <itemizedlist>
    <listitem>
     <para>
      When restoring data to a pre-existing table and the option
      <option>--disable-triggers</> is used,
      <application>pg_restore</application> emits commands
      to disable triggers on user tables before inserting the data then emits commands to
      re-enable them after the data has been inserted.  If the restore is stopped in the
      middle, the system catalogs might be left in the wrong state.
     </para>
    </listitem>

    <listitem>
     <para>
      <application>pg_restore</application> will not restore large objects for a single table. If
      an archive contains large objects, then all large objects will be restored.
     </para>
    </listitem>

   </itemizedlist>
  </para>

  <para>
   See also the <xref linkend="app-pgdump"> documentation for details on
   limitations of <application>pg_dump</application>.
  </para>

  <para>
   Once restored, it is wise to run <command>ANALYZE</> on each
   restored table so the optimizer has useful statistics.
  </para>

 </refsect1>


 <refsect1 id="app-pgrestore-examples">
  <title>Examples</title>

  <para>
   Assume we have dumped a database called <literal>mydb</> into a
   custom-format dump file:

<screen>
<prompt>$</prompt> <userinput>pg_dump -Fc mydb &gt; db.dump</userinput>
</screen>
  </para>

  <para>
   To drop the database and recreate it from the dump:

<screen>
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
<prompt>$</prompt> <userinput>pg_restore -C -d postgres db.dump</userinput>
</screen>

   The database named in the <option>-d</> switch can be any database existing
   in the cluster; <application>pg_restore</> only uses it to issue the
   <command>CREATE DATABASE</> command for <literal>mydb</>.  With
   <option>-C</>, data is always restored into the database name that appears
   in the dump file.
  </para>

  <para>
   To reload the dump into a new database called <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>createdb -T template0 newdb</userinput>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput>
</screen>

   Notice we don't use <option>-C</>, and instead connect directly to the
   database to be restored into.  Also note that we clone the new database
   from <literal>template0</> not <literal>template1</>, to ensure it is
   initially empty.
  </para>

  <para>
   To reorder database items, it is first necessary to dump the table of
   contents of the archive:
<screen>
<prompt>$</prompt> <userinput>pg_restore -l db.dump &gt; db.list</userinput>
</screen>
   The listing file consists of a header and one line for each item, e.g.:
<programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: mydb
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
;     Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
   Semicolons start a comment, and the numbers at the start of lines refer to the
   internal archive ID assigned to each item.
  </para>

  <para>
   Lines in the file can be commented out, deleted, and reordered. For example:
<programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
   could be used as input to <application>pg_restore</application> and would only restore
   items 10 and 6, in that order:
<screen>
<prompt>$</prompt> <userinput>pg_restore -L db.list db.dump</userinput>
</screen>
  </para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-pgdump"></member>
   <member><xref linkend="app-pg-dumpall"></member>
   <member><xref linkend="app-psql"></member>
  </simplelist>
 </refsect1>
</refentry>