--- /dev/null
+<refentry id="APP-PGRESTORE">
+ <refmeta>
+ <refentrytitle id="app-pgrestore-title">
+ <application>pg_restore</application>
+ </refentrytitle>
+ <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>
+ <application>pg_restore</application>
+ </refname>
+ <refpurpose>
+ Restore a <PRODUCTNAME>Postgres</PRODUCTNAME> database from an archive file created by \r
+<APPLICATION>pg_dump</APPLICATION>\r
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <refsynopsisdivinfo>
+ <date>2000-10-11</date>
+ </refsynopsisdivinfo>
+ <synopsis>\r
+pg_restore [ <replaceable class="parameter">archive-file</replaceable> ] \r
+ [ -h <replaceable class="parameter">host</replaceable> ] \r
+ [ -p <replaceable class="parameter">port</replaceable> ] \r
+ [ -t <replaceable class="parameter">table</replaceable> ] \r
+ [ -a ] [ -c ] [-C] [-d <name>] \r
+ [-f <replaceable class="parameter">archive-file</replaceable>] \r
+ [-F <replaceable class="parameter">format</replaceable>] \r
+ [ -i <replaceable class="parameter">index</replaceable> ] \r
+ [ -l ] [ -N ] [ -o ] [ -O ] \r
+ [ -P <replaceable class="parameter">function-name</replaceable> ] [ -r ] [ -R ] \r
+ [ -s ] [ -S ] { -T <replaceable class="parameter">trigger</replaceable> ] [ -u ] \r
+ [-U <replaceable class="parameter">contents-file</replaceable> ] [ -v ] [ -x ] \r
+ </synopsis>
+
+ <refsect2 id="R2-APP-PG-RESTORE-1">
+ <refsect2info>
+ <date>2000-10-11</date>
+ </refsect2info>
+ <title>
+ Inputs
+ </title>
+ <para>
+ <application>pg_restore</application> accepts the following command
+ line arguments:
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable class="parameter">archive-name</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the location of the archive file to be restored.\r
+ If not specified, and no '-f' option is specified, then STDIN is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-a</term>
+ <listitem>
+ <para>
+ Restore only the data, no schema (definitions).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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
+ Include SQL to create the schema.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>
+ <term>-d <replaceable class="parameter">dbname</replaceable></term>
+ <listitem>
+ <para>
+ Connect to database <replaceable class="parameter">dbname</replaceable> and restore \r
+ directly into the database. BLOBs can only be restored by using a direct database connection.\r
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>\r
+ <term>-f</term>\r
+ <listitem>\r
+ <para>\r
+ Specify output file for generated script. Default is STDOUT.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-F <replaceable class="parameter">format</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Specify format of the archive.\r
+ It is not necessary to specify the format, since <APPLICATION>pg_restore</APPLICATION> will \r
+ determine the format automatically. If specified, it can be one of the following:\r
+ </para>\r
+\r
+ <variablelist>\r
+\r
+ <varlistentry>\r
+ <term>t</term>\r
+ <listitem>\r
+ <para>\r
+ archive is a TAR archive. Using this archive format allows reordering and/or \r
+ exclusion of schema elements at the time the database is restored. It is also possible to limit which \r
+ data is reloaded at restore time.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>c</term>\r
+ <listitem>\r
+ <para>\r
+ archive is in the custom format from pg_dump. This is the most flexible format \r
+ in that it allows reordering of data load as well as schema elements. \r
+ This format is also compressed by default.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ </variablelist>\r
+\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-i <replaceable class="parameter">index</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Restore definition for named <replaceable class="parameter">index</replaceable> only.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-l</term>\r
+ <listitem>\r
+ <para>\r
+ List the contents of the archive. The output of this command can be used with the '-U, --use-list' option\r
+ to restrict and reorder the items that are restored.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>
+ <term>-N</term>
+ <listitem>
+ <para>\r
+ Restore items in the original dump order. By default pg_dump will dump items in an order convenient \r
+ to pg_dump, then save the archive in a modified OID order. This option overrides the OID ordering.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-o</term>
+ <listitem>
+ <para>
+ Restore items in the OID order. By default pg_dump will dump items in an order convenient \r
+ to pg_dump, then save the archive in a modified OID order. This option enforces strict OID ordering.\r
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-O</term>
+ <listitem>
+ <para>
+ Prevent any attempt to restore original object ownership. Objects will be owned by the username used\r
+ to attach to the database.\r
+ </para>
+ </listitem>
+ </varlistentry>
+\r
+ <varlistentry>\r
+ <term>-P <replaceable class="parameter">procedure-name</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Specify a procedure or function to be restored.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-r</term>\r
+ <listitem>\r
+ <para>\r
+ Restore items in modified OID order. By default pg_dump will dump items in an order convenient \r
+ to pg_dump, then save the archive in a modified OID order. Most objects\r
+ will be restored in OID order, but some things (eg. RULES & INDEXES) will be restored at the end of\r
+ the process irrespective of their OIDs. This option is the default. \r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+
+ <varlistentry>\r
+ <term>-R</term>\r
+ <listitem>\r
+ <para>\r
+ Prohibit <APPLICATION>pg_restore</APPLICATION> from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> \r
+ statements or reconnecting to the database if directly connected.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-s</term>\r
+ <listitem>\r
+ <para>\r
+ Restore the schema (definitions), no data. Sequence values will be reset.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <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 setting ownership of schema elements.\r
+ By default, <APPLICATION>pg_restore</APPLICATION> will use the current username if it is a superuser.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+
+ <varlistentry>\r
+ <term>-t <replaceable class="parameter">table</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>\r
+ <term>-T <replaceable class="parameter">trigger</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>
+ <term>-u</term>
+ <listitem>
+ <para>
+ Use password authentication. Prompts for username and password.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>\r
+ <term>-U <replaceable class="parameter">list-file</replaceable></term>\r
+ <listitem>\r
+ <para>\r
+ Restore elements in <REPLACEABLE CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the\r
+ order they appear in the file. Lines can be moved and may also be commented out by placing a ';' at the \r
+ start of the line.\r
+ </para>\r
+ </listitem>\r
+ </varlistentry>\r
+\r
+ <varlistentry>
+ <term>-v</term>
+ <listitem>
+ <para>
+ Specifies verbose mode.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-x</term>
+ <listitem>
+ <para>
+ Prevent restoration of ACLs (grant/revoke commands).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <para>
+ <application>pg_restore</application> also accepts
+ the following command line arguments for connection parameters:
+
+ <variablelist>
+ <varlistentry>
+ <term>-h <replaceable class="parameter">host</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the hostname of the machine on which the
+ <application>postmaster</application>
+ is running. Defaults to using a local Unix domain socket
+ rather than an IP connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p <replaceable class="parameter">port</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the Internet TCP/IP port or local Unix domain socket file
+ extension on which the <application>postmaster</application>
+ is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+ environment variable (if set).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-APP-PG-RESTORE-2">
+ <refsect2info>
+ <date>2000-10-11</date>
+ </refsect2info>
+ <title>
+ Outputs
+ </title>
+ <para>
+ <application>pg_restore</application> will create a script file,
+ write to <filename>stdout</filename>, or restore a database directly.
+
+ <variablelist>
+ <varlistentry>
+ <term><computeroutput>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+ </computeroutput></term>
+ <listitem>
+ <para>
+ <application>pg_restore</application> could not attach to the
+ <application>postmaster</application>
+ process on the specified host and port. If you see this message,
+ ensure that the <application>postmaster</application>
+ is running on the proper host and that you have specified the proper
+ port. If your site uses an authentication system, ensure that you
+ have obtained the required authentication credentials.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>
+Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+ </computeroutput></term>
+ <listitem>
+ <para>
+ You do not have a valid entry in the relation <literal>pg_shadow</literal>
+ and and will not be allowed to access <productname>Postgres</productname>.
+ Contact your <productname>Postgres</productname> administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ <note>
+ <para>
+ When a direct database connection is specified using the -d option, <application>pg_restore</application> \r
+ internally executes <command>SQL</command> statements. If you have problems running \r
+ <application>pg_restore</application>,
+ make sure you are able to select information from the database using, for
+ example, <application>psql</application>.
+ </para>
+ </note>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-APP-PG-RESTORE-1">
+ <refsect1info>
+ <date>2000-10-11</date>
+ </refsect1info>
+ <title>
+ Description
+ </title>
+ <para>
+ <application>pg_restore</application> is a utility for restoring a\r
+ <productname>Postgres</productname> database dumped by <application>pg_dump</application>\r
+ from any one of the non-plain-text output formats.\r
+ </para>
+
+ <para>
+ The archive files, new with this relase, contain enough information for \r
+ <application>pg_restore</application> to rebuild the database, but also allow \r
+ <application>pg_restore</application> to be selective about what is restored, \r
+ or even to reorder the items prior to being restored. The archive files should \r
+ also be portable across architectures. <application>pg_dump</application> will \r
+ produce the queries necessary to re-generate all user-defined types, functions, \r
+ tables, indices, aggregates, and operators. In addition, all the data is copied \r
+ out (in text format for scripts) so that it can be readily copied in again.\r
+ </para>
+\r
+ <para>\r
+ <application>pg_restore</application> reads the archive file and outputs the appropriate \r
+ SQL in the required order based on the command parameters. Obviously, it can not restore \r
+ information that is not present in the dump file; so if the dump is made using the \r
+ 'dump data as inserts' option, <application>pg_restore</application> will not be able to\r
+ load the data using <command>COPY</command> statements.\r
+ </para>\r
+\r
+ <para>\r
+ The most flexible output file format is the new 'custom' format (-Fc). It allows for \r
+ selection and reordering of all archived items, and is compressed by default. The TAR \r
+ format (-Ft) is not compressed and it is not possible to reorder\r
+ data load, but it is otherwise quite flexible.\r
+ </para>\r
+\r
+ <para>\r
+ To reorder the items, it is first necessary to dump the contents of the archive:\r
+ <programlisting>\r
+ $ pg_restore acrhive.file --list > archive.lis \r
+ </programlisting>\r
+ This file consists of a header and one line for each item, eg.\r
+ <programlisting>\r
+;\r
+; Archive created at Fri Jul 28 22:28:36 2000\r
+; dbname: birds\r
+; TOC Entries: 74\r
+; Compression: 0\r
+; Dump Version: 1.4-0\r
+; Format: CUSTOM\r
+;\r
+;\r
+; Selected TOC Entries:\r
+;\r
+2; 145344 TABLE species postgres\r
+3; 145344 ACL species\r
+4; 145359 TABLE nt_header postgres\r
+5; 145359 ACL nt_header\r
+6; 145402 TABLE species_records postgres\r
+7; 145402 ACL species_records\r
+8; 145416 TABLE ss_old postgres\r
+9; 145416 ACL ss_old\r
+10; 145433 TABLE map_resolutions postgres\r
+11; 145433 ACL map_resolutions\r
+12; 145443 TABLE hs_old postgres\r
+13; 145443 ACL hs_old\r
+</programlisting>\r
+\r
+ Where semi-colons are comment delimiters, and the numbers at the start of lines refer to the \r
+ internal archive ID assigned to each item. Lines in the file can be commented out, deleted, \r
+ and/or reordered. For example,\r
+ <programlisting>\r
+10; 145433 TABLE map_resolutions postgres\r
+;2; 145344 TABLE species postgres\r
+;4; 145359 TABLE nt_header postgres\r
+6; 145402 TABLE species_records postgres\r
+;8; 145416 TABLE ss_old postgres\r
+ </programlisting>\r
+ </para>\r
+ <para>\r
+ Could be used as input to <application>pg_restore</application> and would only restore \r
+ items 10 and 6, in that order.\r
+ <programlisting>\r
+ $ pg_restore acrhive.file --use=archive.lis \r
+ </programlisting>\r
+ </para>\r
+\r
+ </refsect1>
+
+ <refsect1 id="R1-APP-PG-RESTORE-2">
+ <refsect1info>
+ <date>2000-10-11</date>
+ </refsect1info>
+ <title>
+ Notes
+ </title>
+ <para>
+ See the <application>pg_dump</application> section for details on limitation of\r
+ <application>pg_dump</application>.\r
+ </para>\r
+ <para>
+ The limitations of pg_restore are detailed below.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ When restoring data to a table, <application>pg_restore</application> emits queries \r
+ to disable triggers on user tables before inserting the data then emits queries to \r
+ re-enable them after the data has been inserted. If the restore is stopped in the \r
+ middle, the system catalogs may be left in the wrong state.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <application>pg_restore</application> will not restore BLOBs for a single table. If \r
+ an archive contains BLOBs, then all BLOBs will be restored.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </refsect1>
+
+ <refsect1 id="R1-APP-PG-RESTORE-3">
+ <refsect1info>
+ <date>2000-10-11</date>
+ </refsect1info>
+ <title>
+ Usage
+ </title>
+ <para>
+ To create a custom archive for a database of the same name as the user:
+
+ <programlisting>
+$ pg_dump -Fc > db.out
+ </programlisting>
+ </para>
+
+ <para>\r
+ To reload this database:\r
+\r
+ <programlisting>\r
+$ pg_restore db.out | psql -e database\r
+ </programlisting>\r
+ </para>\r
+\r
+ <para>\r
+ To dump a database called mydb that contains BLOBs to a TAR file:\r
+\r
+ <programlisting>\r
+$ pg_dump -Ft mydb --blobs > 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
+\r
+ </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:
+-->
projects / postgresql / commitdiff