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

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