granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/pg_restore.sgml

   1 <!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.82 2009/08/07 20:54:31 alvherre Exp $ -->
   2
   3 <refentry id="APP-PGRESTORE">
   4  <refmeta>
   5   <refentrytitle>pg_restore</refentrytitle>
   6   <manvolnum>1</manvolnum>
   7   <refmiscinfo>Application</refmiscinfo>
   8  </refmeta>
   9
  10  <refnamediv>
  11   <refname>pg_restore</refname>
  12
  13   <refpurpose>
  14    restore a <productname>PostgreSQL</productname> database from an
  15    archive file created by <application>pg_dump</application>
  16   </refpurpose>
  17  </refnamediv>
  18
  19  <indexterm zone="app-pgrestore">
  20   <primary>pg_restore</primary>
  21  </indexterm>
  22
  23  <refsynopsisdiv>
  24   <cmdsynopsis>
  25    <command>pg_restore</command>
  26    <arg rep="repeat"><replaceable>option</replaceable></arg>
  27    <arg><replaceable>filename</replaceable></arg>
  28   </cmdsynopsis>
  29  </refsynopsisdiv>
  30
  31
  32  <refsect1 id="app-pgrestore-description">
  33   <title>Description</title>
  34
  35   <para>
  36    <application>pg_restore</application> is a utility for restoring a
  37    <productname>PostgreSQL</productname> database from an archive
  38    created by <xref linkend="app-pgdump"> in one of the non-plain-text
  39    formats.  It will issue the commands necessary to reconstruct the
  40    database to the state it was in at the time it was saved.  The
  41    archive files also allow <application>pg_restore</application> to
  42    be selective about what is restored, or even to reorder the items
  43    prior to being restored. The archive files are designed to be
  44    portable across architectures.
  45   </para>
  46
  47   <para>
  48    <application>pg_restore</application> can operate in two modes.
  49    If a database name is specified, the archive is restored directly into
  50    the database.  Otherwise, a script containing the SQL
  51    commands necessary to rebuild the database is created and written
  52    to a file or standard output.  The script output is equivalent to
  53    the plain text output format of <application>pg_dump</application>.
  54    Some of the options controlling the output are therefore analogous to
  55    <application>pg_dump</application> options.
  56   </para>
  57
  58   <para>
  59    Obviously, <application>pg_restore</application> cannot restore information
  60    that is not present in the archive file.  For instance, if the
  61    archive was made using the <quote>dump data as
  62    <command>INSERT</command> commands</quote> option,
  63    <application>pg_restore</application> will not be able to load the data
  64    using <command>COPY</command> statements.
  65   </para>
  66  </refsect1>
  67
  68  <refsect1 id="app-pgrestore-options">
  69   <title>Options</title>
  70
  71    <para>
  72     <application>pg_restore</application> accepts the following command
  73     line arguments.
  74
  75     <variablelist>
  76      <varlistentry>
  77       <term><replaceable class="parameter">filename</replaceable></term>
  78       <listitem>
  79        <para>
  80        Specifies the location of the archive file to be restored.
  81        If not specified, the standard input is used.
  82        </para>
  83       </listitem>
  84      </varlistentry>
  85
  86      <varlistentry>
  87       <term><option>-a</option></term>
  88       <term><option>--data-only</option></term>
  89       <listitem>
  90        <para>
  91         Restore only the data, not the schema (data definitions).
  92        </para>
  93       </listitem>
  94      </varlistentry>
  95
  96      <varlistentry>
  97       <term><option>-c</option></term>
  98       <term><option>--clean</option></term>
  99       <listitem>
 100        <para>
 101         Clean (drop) database objects before recreating them.
 102        </para>
 103       </listitem>
 104      </varlistentry>
 105
 106      <varlistentry>
 107       <term><option>-C</option></term>
 108       <term><option>--create</option></term>
 109       <listitem>
 110        <para>
 111         Create the database before restoring into it.  (When this
 112         option is used, the database named with <option>-d</option> is
 113         used only to issue the initial <command>CREATE DATABASE</>
 114         command.  All data is restored into the database name that
 115         appears in the archive.)
 116        </para>
 117       </listitem>
 118      </varlistentry>
 119
 120      <varlistentry>
 121       <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
 122       <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
 123       <listitem>
 124        <para>
 125         Connect to database <replaceable
 126         class="parameter">dbname</replaceable> and restore directly
 127         into the database.
 128        </para>
 129       </listitem>
 130      </varlistentry>
 131
 132      <varlistentry>
 133       <term><option>-e</option></term>
 134       <term><option>--exit-on-error</option></term>
 135       <listitem>
 136        <para>
 137         Exit if an error is encountered while sending SQL commands to
 138         the database. The default is to continue and to display a count of
 139         errors at the end of the restoration.
 140        </para>
 141       </listitem>
 142      </varlistentry>
 143
 144      <varlistentry>
 145       <term><option>-f <replaceable>filename</replaceable></option></term>
 146       <term><option>--file=<replaceable>filename</replaceable></option></term>
 147       <listitem>
 148        <para>
 149         Specify output file for generated script, or for the listing
 150         when used with <option>-l</option>. Default is the standard
 151         output.
 152        </para>
 153       </listitem>
 154      </varlistentry>
 155
 156      <varlistentry>
 157       <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
 158       <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
 159       <listitem>
 160        <para>
 161         Specify format of the archive.  It is not necessary to specify
 162         the format, since <application>pg_restore</application> will
 163         determine the format automatically. If specified, it can be
 164         one of the following:
 165
 166        <variablelist>
 167         <varlistentry>
 168          <term><literal>t</></term>
 169          <term><literal>tar</></term>
 170          <listitem>
 171           <para>
 172            The archive is a <command>tar</command> archive. Using this
 173            archive format allows reordering and/or exclusion of schema
 174            elements at the time the database is restored. It is also
 175            possible to limit which data is reloaded at restore time.
 176           </para>
 177          </listitem>
 178         </varlistentry>
 179
 180         <varlistentry>
 181          <term><literal>c</></term>
 182          <term><literal>custom</></term>
 183          <listitem>
 184           <para>
 185            The archive is in the custom format of
 186            <application>pg_dump</application>. This is the most
 187            flexible format in that it allows reordering of data load
 188            as well as schema elements.  This format is also compressed
 189            by default.
 190           </para>
 191          </listitem>
 192         </varlistentry>
 193        </variablelist>
 194        </para>
 195       </listitem>
 196      </varlistentry>
 197
 198      <varlistentry>
 199       <term><option>-i</option></term>
 200       <term><option>--ignore-version</option></term>
 201       <listitem>
 202        <para>
 203         A deprecated option that is now ignored.
 204        </para>
 205       </listitem>
 206      </varlistentry>
 207
 208      <varlistentry>
 209       <term><option>-I <replaceable class="parameter">index</replaceable></option></term>
 210       <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
 211       <listitem>
 212        <para>
 213         Restore definition of named index only.
 214        </para>
 215       </listitem>
 216      </varlistentry>
 217
 218      <varlistentry>
 219       <term><option>-j <replaceable class="parameter">number-of-jobs</replaceable></option></term>
 220       <term><option>--jobs=<replaceable class="parameter">number-of-jobs</replaceable></option></term>
 221       <listitem>
 222        <para>
 223         Run the most time-consuming parts
 224         of <application>pg_restore</> &mdash; those which load data,
 225         create indexes, or create constraints &mdash; using multiple
 226         concurrent jobs.  This option can dramatically reduce the time
 227         to restore a large database to a server running on a
 228         multi-processor machine.
 229        </para>
 230
 231        <para>
 232         Each job is one process or one thread, depending on the
 233         operating system, and uses a separate connection to the
 234         server.
 235        </para>
 236
 237        <para>
 238         The optimal value for this option depends on the hardware
 239         setup of the server, of the client, and of the network.
 240         Factors include the number of CPU cores and the disk setup.  A
 241         good place to start is the number of CPU cores on the server,
 242         but values larger than that can also lead to faster restore
 243         times in many cases.  Of course, values that are too high will
 244         lead to decreasing performance because of thrashing.
 245        </para>
 246
 247        <para>
 248         Only the custom archive format is supported with this option.
 249         The input file must be a regular file (not, for example, a
 250         pipe).  This option is ignored when emitting a script rather
 251         than connecting directly to a database server.  Also, multiple
 252         jobs cannot be used together with the
 253         option <option>--single-transaction</option>.
 254        </para>
 255       </listitem>
 256      </varlistentry>
 257
 258      <varlistentry>
 259       <term><option>-l</option></term>
 260       <term><option>--list</option></term>
 261       <listitem>
 262        <para>
 263         List the contents of the archive. The output of this operation
 264         can be used with the <option>-L</option> option to restrict
 265         and reorder the items that are restored.
 266        </para>
 267       </listitem>
 268      </varlistentry>
 269
 270      <varlistentry>
 271       <term><option>-L <replaceable class="parameter">list-file</replaceable></option></term>
 272       <term><option>--use-list=<replaceable class="parameter">list-file</replaceable></option></term>
 273       <listitem>
 274        <para>
 275         Restore elements in <replaceable class="PARAMETER">
 276         list-file</replaceable> only, and in the
 277         order they appear in the file. Lines can be moved and can also
 278         be commented out by placing a <literal>;</literal> at the
 279         start of the line.  (See below for examples.)
 280        </para>
 281       </listitem>
 282      </varlistentry>
 283
 284      <varlistentry>
 285       <term><option>-n <replaceable class="parameter">namespace</replaceable></option></term>
 286       <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
 287       <listitem>
 288        <para>
 289         Restore only objects that are in the named schema.  This can be
 290         combined with the <option>-t</option> option to restore just a
 291         specific table.
 292        </para>
 293       </listitem>
 294      </varlistentry>
 295
 296      <varlistentry>
 297       <term><option>-O</option></term>
 298       <term><option>--no-owner</option></term>
 299       <listitem>
 300        <para>
 301         Do not output commands to set
 302         ownership of objects to match the original database.
 303         By default, <application>pg_restore</application> issues
 304         <command>ALTER OWNER</> or
 305         <command>SET SESSION AUTHORIZATION</command>
 306         statements to set ownership of created schema elements.
 307         These statements will fail unless the initial connection to the
 308         database is made by a superuser
 309         (or the same user that owns all of the objects in the script).
 310         With <option>-O</option>, any user name can be used for the
 311         initial connection, and this user will own all the created objects.
 312        </para>
 313       </listitem>
 314      </varlistentry>
 315
 316      <varlistentry>
 317       <term><option>--no-tablespaces</option></term>
 318       <listitem>
 319        <para>
 320         Do not output commands to select tablespaces.
 321         With this option, all objects will be created in whichever
 322         tablespace is the default during restore.
 323        </para>
 324       </listitem>
 325      </varlistentry>
 326
 327      <varlistentry>
 328       <term><option>-P <replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
 329       <term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
 330       <listitem>
 331        <para>
 332         Restore the named function only.  Be careful to spell the function
 333         name and arguments exactly as they appear in the dump file's table
 334         of contents.
 335        </para>
 336       </listitem>
 337      </varlistentry>
 338
 339      <varlistentry>
 340       <term><option>-R</option></term>
 341       <term><option>--no-reconnect</option></term>
 342       <listitem>
 343        <para>
 344         This option is obsolete but still accepted for backwards
 345         compatibility.
 346        </para>
 347       </listitem>
 348      </varlistentry>
 349
 350      <varlistentry>
 351       <term><option>-s</option></term>
 352       <term><option>--schema-only</option></term>
 353       <listitem>
 354        <para>
 355         Restore only the schema (data definitions), not the data (table
 356         contents).  Sequence current values will not be restored, either.
 357         (Do not confuse this with the <option>--schema</> option, which
 358         uses the word <quote>schema</> in a different meaning.)
 359        </para>
 360       </listitem>
 361      </varlistentry>
 362
 363      <varlistentry>
 364       <term><option>-S <replaceable class="parameter">username</replaceable></option></term>
 365       <term><option>--superuser=<replaceable class="parameter">username</replaceable></option></term>
 366       <listitem>
 367        <para>
 368         Specify the superuser user name to use when disabling triggers.
 369         This is only relevant if <option>--disable-triggers</> is used.
 370        </para>
 371       </listitem>
 372      </varlistentry>
 373
 374      <varlistentry>
 375       <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
 376       <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
 377       <listitem>
 378        <para>
 379         Restore definition and/or data of named table only.
 380        </para>
 381       </listitem>
 382      </varlistentry>
 383
 384      <varlistentry>
 385       <term><option>-T <replaceable class="parameter">trigger</replaceable></option></term>
 386       <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
 387       <listitem>
 388        <para>
 389         Restore named trigger only.
 390        </para>
 391       </listitem>
 392      </varlistentry>
 393
 394      <varlistentry>
 395       <term><option>-v</option></term>
 396       <term><option>--verbose</option></term>
 397       <listitem>
 398        <para>
 399         Specifies verbose mode.
 400        </para>
 401       </listitem>
 402      </varlistentry>
 403
 404      <varlistentry>
 405       <term><option>-x</option></term>
 406       <term><option>--no-privileges</option></term>
 407       <term><option>--no-acl</option></term>
 408       <listitem>
 409        <para>
 410         Prevent restoration of access privileges (grant/revoke commands).
 411        </para>
 412       </listitem>
 413      </varlistentry>
 414
 415      <varlistentry>
 416       <term><option>--disable-triggers</></term>
 417       <listitem>
 418        <para>
 419         This option is only relevant when performing a data-only restore.
 420         It instructs <application>pg_restore</application> to execute commands
 421         to temporarily disable triggers on the target tables while
 422         the data is reloaded.  Use this if you have referential
 423         integrity checks or other triggers on the tables that you
 424         do not want to invoke during data reload.
 425        </para>
 426
 427        <para>
 428         Presently, the commands emitted for
 429         <option>--disable-triggers</> must be done as superuser.  So, you
 430         should also specify a superuser name with <option>-S</>, or
 431         preferably run <application>pg_restore</application> as a
 432         <productname>PostgreSQL</> superuser.
 433        </para>
 434       </listitem>
 435      </varlistentry>
 436
 437      <varlistentry>
 438       <term><option>--use-set-session-authorization</option></term>
 439       <listitem>
 440        <para>
 441         Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
 442         instead of <command>ALTER OWNER</> commands to determine object
 443         ownership.  This makes the dump more standards compatible, but
 444         depending on the history of the objects in the dump, might not restore
 445         properly.
 446        </para>
 447       </listitem>
 448      </varlistentry>
 449
 450      <varlistentry>
 451       <term><option>--no-data-for-failed-tables</option></term>
 452       <listitem>
 453        <para>
 454         By default, table data is restored even if the creation command
 455         for the table failed (e.g., because it already exists).
 456         With this option, data for such a table is skipped.
 457         This behavior is useful if the target database already
 458         contains the desired table contents.  For example,
 459         auxiliary tables for <productname>PostgreSQL</> extensions
 460         such as <productname>PostGIS</> might already be loaded in
 461         the target database; specifying this option prevents duplicate
 462         or obsolete data from being loaded into them.
 463        </para>
 464
 465        <para>
 466         This option is effective only when restoring directly into a
 467         database, not when producing SQL script output.
 468        </para>
 469       </listitem>
 470      </varlistentry>
 471
 472      <varlistentry>
 473       <term><option>-1</option></term>
 474       <term><option>--single-transaction</option></term>
 475       <listitem>
 476        <para>
 477         Execute the restore as a single transaction (that is, wrap the
 478         emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
 479         ensures that either all the commands complete successfully, or no
 480         changes are applied. This option implies
 481         <option>--exit-on-error</>.
 482        </para>
 483       </listitem>
 484      </varlistentry>
 485
 486     </variablelist>
 487    </para>
 488
 489    <para>
 490     <application>pg_restore</application> also accepts
 491     the following command line arguments for connection parameters:
 492
 493     <variablelist>
 494      <varlistentry>
 495       <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
 496       <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
 497       <listitem>
 498        <para>
 499         Specifies the host name of the machine on which the server is
 500         running.  If the value begins with a slash, it is used as the
 501         directory for the Unix domain socket. The default is taken
 502         from the <envar>PGHOST</envar> environment variable, if set,
 503         else a Unix domain socket connection is attempted.
 504        </para>
 505       </listitem>
 506      </varlistentry>
 507
 508      <varlistentry>
 509       <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
 510       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
 511       <listitem>
 512        <para>
 513         Specifies the TCP port or local Unix domain socket file
 514         extension on which the server is listening for connections.
 515         Defaults to the <envar>PGPORT</envar> environment variable, if
 516         set, or a compiled-in default.
 517         </para>
 518       </listitem>
 519      </varlistentry>
 520
 521      <varlistentry>
 522       <term><option>-U <replaceable>username</replaceable></option></term>
 523       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
 524       <listitem>
 525        <para>
 526         User name to connect as.
 527        </para>
 528       </listitem>
 529      </varlistentry>
 530
 531      <varlistentry>
 532       <term><option>-w</></term>
 533       <term><option>--no-password</></term>
 534       <listitem>
 535        <para>
 536         Never issue a password prompt.  If the server requires
 537         password authentication and a password is not available by
 538         other means such as a <filename>.pgpass</filename> file, the
 539         connection attempt will fail.  This option can be useful in
 540         batch jobs and scripts where no user is present to enter a
 541         password.
 542        </para>
 543       </listitem>
 544      </varlistentry>
 545
 546      <varlistentry>
 547       <term><option>-W</option></term>
 548       <term><option>--password</option></term>
 549       <listitem>
 550        <para>
 551         Force <application>pg_restore</application> to prompt for a
 552         password before connecting to a database.
 553        </para>
 554
 555        <para>
 556         This option is never essential, since
 557         <application>pg_restore</application> will automatically prompt
 558         for a password if the server demands password authentication.
 559         However, <application>pg_restore</application> will waste a
 560         connection attempt finding out that the server wants a password.
 561         In some cases it is worth typing <option>-W</> to avoid the extra
 562         connection attempt.
 563        </para>
 564       </listitem>
 565      </varlistentry>
 566
 567      <varlistentry>
 568       <term><option>--role=<replaceable class="parameter">rolename</replaceable></option></term>
 569       <listitem>
 570        <para>
 571         Specifies a role name to be used to perform the restore.
 572         This option causes <application>pg_restore</> to issue a
 573         <command>SET ROLE</> <replaceable class="parameter">rolename</>
 574         command after connecting to the database. It is useful when the
 575         authenticated user (specified by <option>-U</>) lacks privileges
 576         needed by <application>pg_restore</>, but can switch to a role with
 577         the required rights.  Some installations have a policy against
 578         logging in directly as a superuser, and use of this option allows
 579         restores to be performed without violating the policy.
 580        </para>
 581       </listitem>
 582      </varlistentry>
 583
 584     </variablelist>
 585    </para>
 586  </refsect1>
 587
 588
 589  <refsect1>
 590   <title>Environment</title>
 591
 592   <variablelist>
 593    <varlistentry>
 594     <term><envar>PGHOST</envar></term>
 595     <term><envar>PGOPTIONS</envar></term>
 596     <term><envar>PGPORT</envar></term>
 597     <term><envar>PGUSER</envar></term>
 598
 599     <listitem>
 600      <para>
 601       Default connection parameters
 602      </para>
 603     </listitem>
 604    </varlistentry>
 605   </variablelist>
 606
 607   <para>
 608    This utility, like most other <productname>PostgreSQL</> utilities,
 609    also uses the environment variables supported by <application>libpq</>
 610    (see <xref linkend="libpq-envars">).
 611   </para>
 612
 613  </refsect1>
 614
 615
 616  <refsect1 id="app-pgrestore-diagnostics">
 617   <title>Diagnostics</title>
 618
 619   <para>
 620    When a direct database connection is specified using the
 621    <option>-d</option> option, <application>pg_restore</application>
 622    internally executes <acronym>SQL</acronym> statements. If you have
 623    problems running <application>pg_restore</application>, make sure
 624    you are able to select information from the database using, for
 625    example, <xref linkend="app-psql">.  Also, any default connection
 626    settings and environment variables used by the
 627    <application>libpq</application> front-end library will apply.
 628   </para>
 629  </refsect1>
 630
 631
 632  <refsect1 id="app-pgrestore-notes">
 633   <title>Notes</title>
 634
 635   <para>
 636    If your installation has any local additions to the
 637    <literal>template1</> database, be careful to load the output of
 638    <application>pg_restore</application> into a truly empty database;
 639    otherwise you are likely to get errors due to duplicate definitions
 640    of the added objects.  To make an empty database without any local
 641    additions, copy from <literal>template0</> not <literal>template1</>, for example:
 642 <programlisting>
 643 CREATE DATABASE foo WITH TEMPLATE template0;
 644 </programlisting>
 645   </para>
 646
 647   <para>
 648    The limitations of <application>pg_restore</application> are detailed below.
 649
 650    <itemizedlist>
 651     <listitem>
 652      <para>
 653       When restoring data to a pre-existing table and the option
 654       <option>--disable-triggers</> is used,
 655       <application>pg_restore</application> emits commands
 656       to disable triggers on user tables before inserting the data then emits commands to
 657       re-enable them after the data has been inserted.  If the restore is stopped in the
 658       middle, the system catalogs might be left in the wrong state.
 659      </para>
 660     </listitem>
 661
 662     <listitem>
 663      <para>
 664       <application>pg_restore</application> cannot restore large objects
 665       selectively, for instance only those for a specific table.  If
 666       an archive contains large objects, then all large objects will be
 667       restored, or none of them if they are excluded via <option>-L</option>,
 668       <option>-t</option>, or other options.
 669      </para>
 670     </listitem>
 671
 672    </itemizedlist>
 673   </para>
 674
 675   <para>
 676    See also the <xref linkend="app-pgdump"> documentation for details on
 677    limitations of <application>pg_dump</application>.
 678   </para>
 679
 680   <para>
 681    Once restored, it is wise to run <command>ANALYZE</> on each
 682    restored table so the optimizer has useful statistics; see
 683    <xref linkend="vacuum-for-statistics"> and
 684    <xref linkend="autovacuum"> for more information.
 685   </para>
 686
 687  </refsect1>
 688
 689
 690  <refsect1 id="app-pgrestore-examples">
 691   <title>Examples</title>
 692
 693   <para>
 694    Assume we have dumped a database called <literal>mydb</> into a
 695    custom-format dump file:
 696
 697 <screen>
 698 <prompt>$</prompt> <userinput>pg_dump -Fc mydb &gt; db.dump</userinput>
 699 </screen>
 700   </para>
 701
 702   <para>
 703    To drop the database and recreate it from the dump:
 704
 705 <screen>
 706 <prompt>$</prompt> <userinput>dropdb mydb</userinput>
 707 <prompt>$</prompt> <userinput>pg_restore -C -d postgres db.dump</userinput>
 708 </screen>
 709
 710    The database named in the <option>-d</> switch can be any database existing
 711    in the cluster; <application>pg_restore</> only uses it to issue the
 712    <command>CREATE DATABASE</> command for <literal>mydb</>.  With
 713    <option>-C</>, data is always restored into the database name that appears
 714    in the dump file.
 715   </para>
 716
 717   <para>
 718    To reload the dump into a new database called <literal>newdb</>:
 719
 720 <screen>
 721 <prompt>$</prompt> <userinput>createdb -T template0 newdb</userinput>
 722 <prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput>
 723 </screen>
 724
 725    Notice we don't use <option>-C</>, and instead connect directly to the
 726    database to be restored into.  Also note that we clone the new database
 727    from <literal>template0</> not <literal>template1</>, to ensure it is
 728    initially empty.
 729   </para>
 730
 731   <para>
 732    To reorder database items, it is first necessary to dump the table of
 733    contents of the archive:
 734 <screen>
 735 <prompt>$</prompt> <userinput>pg_restore -l db.dump &gt; db.list</userinput>
 736 </screen>
 737    The listing file consists of a header and one line for each item, e.g.:
 738 <programlisting>
 739 ;
 740 ; Archive created at Fri Jul 28 22:28:36 2000
 741 ;     dbname: mydb
 742 ;     TOC Entries: 74
 743 ;     Compression: 0
 744 ;     Dump Version: 1.4-0
 745 ;     Format: CUSTOM
 746 ;
 747 ;
 748 ; Selected TOC Entries:
 749 ;
 750 2; 145344 TABLE species postgres
 751 3; 145344 ACL species
 752 4; 145359 TABLE nt_header postgres
 753 5; 145359 ACL nt_header
 754 6; 145402 TABLE species_records postgres
 755 7; 145402 ACL species_records
 756 8; 145416 TABLE ss_old postgres
 757 9; 145416 ACL ss_old
 758 10; 145433 TABLE map_resolutions postgres
 759 11; 145433 ACL map_resolutions
 760 12; 145443 TABLE hs_old postgres
 761 13; 145443 ACL hs_old
 762 </programlisting>
 763    Semicolons start a comment, and the numbers at the start of lines refer to the
 764    internal archive ID assigned to each item.
 765   </para>
 766
 767   <para>
 768    Lines in the file can be commented out, deleted, and reordered. For example:
 769 <programlisting>
 770 10; 145433 TABLE map_resolutions postgres
 771 ;2; 145344 TABLE species postgres
 772 ;4; 145359 TABLE nt_header postgres
 773 6; 145402 TABLE species_records postgres
 774 ;8; 145416 TABLE ss_old postgres
 775 </programlisting>
 776    could be used as input to <application>pg_restore</application> and would only restore
 777    items 10 and 6, in that order:
 778 <screen>
 779 <prompt>$</prompt> <userinput>pg_restore -L db.list db.dump</userinput>
 780 </screen>
 781   </para>
 782
 783  </refsect1>
 784
 785  <refsect1>
 786   <title>See Also</title>
 787
 788   <simplelist type="inline">
 789    <member><xref linkend="app-pgdump"></member>
 790    <member><xref linkend="app-pg-dumpall"></member>
 791    <member><xref linkend="app-psql"></member>
 792   </simplelist>
 793  </refsect1>
 794 </refentry>