<option>-W</option> to avoid the extra
connection attempt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--role=<replaceable class="parameter">rolename</replaceable></option></term>
<listitem>
<para>
Specifies a role name to be used to perform the restore.
This option causes <application>pg_restore</application> to issue a
<command>SET ROLE</command> <replaceable class="parameter">rolename</replaceable>
command after connecting to the database. It is useful when the
authenticated user (specified by <option>-U</option>) lacks privileges
needed by <application>pg_restore</application>, but can switch to a role with
the required rights. Some installations have a policy against
logging in directly as a superuser, and use of this option allows
restores to be performed without violating the policy.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>PGHOST</envar></term>
<term><envar>PGOPTIONS</envar></term>
<term><envar>PGPORT</envar></term>
<term><envar>PGUSER</envar></term>
<listitem>
<para>
Default connection parameters
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>PG_COLOR</envar></term>
<listitem>
<para>
Specifies whether to use color in diagnostic messages. Possible values
are <literal>always</literal>, <literal>auto</literal> and
<literal>never</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
This utility, like most other <productname>PostgreSQL</productname> utilities,
also uses the environment variables supported by <application>libpq</application>
(see <xref linkend="libpq-envars"/>). However, it does not read
<envar>PGDATABASE</envar> when a database name is not supplied.
</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</literal> 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</literal> not <literal>template1</literal>, 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</option> 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> cannot restore large objects
selectively; for instance,