pg_restore.sgml

PostgreSQL7.4.6 for Linux

       <para>
        Specify the superuser user name to use when disabling triggers.
	This is only relevant if <option>--disable-triggers</> is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
      <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
      <listitem>
       <para>
        Restore definition and/or data of named table only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-T <replaceable class="parameter">trigger</replaceable></option></term>
      <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
      <listitem>
       <para>
        Restore named trigger only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</option></term>
      <term><option>--verbose</option></term>
      <listitem>
       <para>
	Specifies verbose mode.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <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>-X use-set-session-authorization</option></term>
      <term><option>--use-set-session-authorization</option></term>
      <listitem>
       <para>
        This option is obsolete but still accepted for backwards
	compatibility.
        <application>pg_restore</application> now always behaves in the
	way formerly selected by this option.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-X disable-triggers</></term>
      <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>

    </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>
      <listitem>
       <para>
        Connect as the given user
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</option></term>
      <listitem>
       <para>
        Force a password prompt.  This should happen automatically if
        the server requires password authentication.
       </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>
 </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, <application>psql</application>.
  </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 may 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>
   To dump a database called <literal>mydb</> that contains
   large objects to a <filename>tar</filename> file:

<screen>
<prompt>$</prompt> <userinput>pg_dump -Ft -b mydb &gt; db.tar</userinput>
</screen>
  </para>

  <para>
   To reload this database (with large objects) to an
   existing database called <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
</screen>
  </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 archive.file &gt; archive.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: birds
;     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 archive.list archive.file</userinput>
</screen>
  </para>

 </refsect1>

 <refsect1>
  <title>History</title>

  <para>
   The <application>pg_restore</application> utility first appeared in
   <productname>PostgreSQL</productname> 7.1.
  </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>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->