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