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.60 2006/08/01 18:21:44 momjian 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 archive file created by pg_dump
  15   </refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="app-pgrestore">
  19   <primary>pg_restore</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>pg_restore</command>
  25    <arg rep="repeat"><replaceable>option</replaceable></arg>
  26    <arg><replaceable>filename</replaceable></arg>
  27   </cmdsynopsis>
  28  </refsynopsisdiv>
  29
  30
  31  <refsect1 id="app-pgrestore-description">
  32   <title>Description</title>
  33
  34   <para>
  35    <application>pg_restore</application> is a utility for restoring a
  36    <productname>PostgreSQL</productname> database from an archive
  37    created by <xref linkend="app-pgdump"> in one of the non-plain-text
  38    formats.  It will issue the commands necessary to reconstruct the
  39    database to the state it was in at the time it was saved.  The
  40    archive files also allow <application>pg_restore</application> to
  41    be selective about what is restored, or even to reorder the items
  42    prior to being restored. The archive files are designed to be
  43    portable across architectures.
  44   </para>
  45
  46   <para>
  47    <application>pg_restore</application> can operate in two modes.
  48    If a database name is specified, the archive is restored directly into
  49    the database.  Otherwise, a script containing the SQL
  50    commands necessary to rebuild the database is created and written
  51    to a file or standard output.  The script output is equivalent to
  52    the plain text output format of <application>pg_dump</application>.
  53    Some of the options controlling the output are therefore analogous to
  54    <application>pg_dump</application> options.
  55   </para>
  56
  57   <para>
  58    Obviously, <application>pg_restore</application> cannot restore information
  59    that is not present in the archive file.  For instance, if the
  60    archive was made using the <quote>dump data as
  61    <command>INSERT</command> commands</quote> option,
  62    <application>pg_restore</application> will not be able to load the data
  63    using <command>COPY</command> statements.
  64   </para>
  65  </refsect1>
  66
  67  <refsect1 id="app-pgrestore-options">
  68   <title>Options</title>
  69
  70    <para>
  71     <application>pg_restore</application> accepts the following command
  72     line arguments.
  73
  74     <variablelist>
  75      <varlistentry>
  76       <term><replaceable class="parameter">filename</replaceable></term>
  77       <listitem>
  78        <para>
  79        Specifies the location of the archive file to be restored.
  80        If not specified, the standard input is used.
  81        </para>
  82       </listitem>
  83      </varlistentry>
  84
  85      <varlistentry>
  86       <term><option>-a</option></term>
  87       <term><option>--data-only</option></term>
  88       <listitem>
  89        <para>
  90         Restore only the data, not the schema (data definitions).
  91        </para>
  92       </listitem>
  93      </varlistentry>
  94
  95      <varlistentry>
  96       <term><option>-c</option></term>
  97       <term><option>--clean</option></term>
  98       <listitem>
  99        <para>
 100         Clean (drop) database objects before recreating them.
 101        </para>
 102       </listitem>
 103      </varlistentry>
 104
 105      <varlistentry>
 106       <term><option>-C</option></term>
 107       <term><option>--create</option></term>
 108       <listitem>
 109        <para>
 110         Create the database before restoring into it.  (When this
 111         option is used, the database named with <option>-d</option> is
 112         used only to issue the initial <command>CREATE DATABASE</>
 113         command.  All data is restored into the database name that
 114         appears in the archive.)
 115        </para>
 116       </listitem>
 117      </varlistentry>
 118
 119      <varlistentry>
 120       <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
 121       <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
 122       <listitem>
 123        <para>
 124         Connect to database <replaceable
 125         class="parameter">dbname</replaceable> and restore directly
 126         into the database.
 127        </para>
 128       </listitem>
 129      </varlistentry>
 130
 131      <varlistentry>
 132       <term><option>-e</option></term>
 133       <term><option>--exit-on-error</option></term>
 134       <listitem>
 135        <para>
 136         Exit if an error is encountered while sending SQL commands to
 137         the database. The default is to continue and to display a count of
 138         errors at the end of the restoration.
 139        </para>
 140       </listitem>
 141      </varlistentry>
 142
 143      <varlistentry>
 144       <term><option>-f <replaceable>filename</replaceable></option></term>
 145       <term><option>--file=<replaceable>filename</replaceable></option></term>
 146       <listitem>
 147        <para>
 148         Specify output file for generated script, or for the listing
 149         when used with <option>-l</option>. Default is the standard
 150         output.
 151        </para>
 152       </listitem>
 153      </varlistentry>
 154
 155      <varlistentry>
 156       <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
 157       <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
 158       <listitem>
 159        <para>
 160         Specify format of the archive.  It is not necessary to specify
 161         the format, since <application>pg_restore</application> will
 162         determine the format automatically. If specified, it can be
 163         one of the following:
 164
 165        <variablelist>
 166         <varlistentry>
 167          <term><literal>t</></term>
 168          <term><literal>tar</></term>
 169          <listitem>
 170           <para>
 171            The archive is a <command>tar</command> archive. Using this
 172            archive format allows reordering and/or exclusion of schema
 173            elements at the time the database is restored. It is also
 174            possible to limit which data is reloaded at restore time.
 175           </para>
 176          </listitem>
 177         </varlistentry>
 178
 179         <varlistentry>
 180          <term><literal>c</></term>
 181          <term><literal>custom</></term>
 182          <listitem>
 183           <para>
 184            The archive is in the custom format of
 185            <application>pg_dump</application>. This is the most
 186            flexible format in that it allows reordering of data load
 187            as well as schema elements.  This format is also compressed
 188            by default.
 189           </para>
 190          </listitem>
 191         </varlistentry>
 192        </variablelist>
 193        </para>
 194       </listitem>
 195      </varlistentry>
 196
 197      <varlistentry>
 198       <term><option>-i</option></term>
 199       <term><option>--ignore-version</option></term>
 200       <listitem>
 201        <para>
 202         Ignore database version checks.
 203        </para>
 204       </listitem>
 205      </varlistentry>
 206
 207      <varlistentry>
 208       <term><option>-I <replaceable class="parameter">index</replaceable></option></term>
 209       <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
 210       <listitem>
 211        <para>
 212         Restore definition of named index only.
 213        </para>
 214       </listitem>
 215      </varlistentry>
 216
 217      <varlistentry>
 218       <term><option>-l</option></term>
 219       <term><option>--list</option></term>
 220       <listitem>
 221        <para>
 222         List the contents of the archive. The output of this operation
 223         can be used with the <option>-L</option> option to restrict
 224         and reorder the items that are restored.
 225        </para>
 226       </listitem>
 227      </varlistentry>
 228
 229      <varlistentry>
 230       <term><option>-L <replaceable class="parameter">list-file</replaceable></option></term>
 231       <term><option>--use-list=<replaceable class="parameter">list-file</replaceable></option></term>
 232       <listitem>
 233        <para>
 234         Restore elements in <replaceable class="PARAMETER">
 235         list-file</replaceable> only, and in the
 236         order they appear in the file. Lines can be moved and may also
 237         be commented out by placing a <literal>;</literal> at the
 238         start of the line.  (See below for examples.)
 239        </para>
 240       </listitem>
 241      </varlistentry>
 242
 243      <varlistentry>
 244       <term><option>-n <replaceable class="parameter">namespace</replaceable></option></term>
 245       <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
 246       <listitem>
 247        <para>
 248         Restore only objects that are in the named schema.  This can be
 249         combined with the <option>-t</option> option to restore just a
 250         specific table.
 251        </para>
 252       </listitem>
 253      </varlistentry>
 254
 255      <varlistentry>
 256       <term><option>-O</option></term>
 257       <term><option>--no-owner</option></term>
 258       <listitem>
 259        <para>
 260         Do not output commands to set
 261         ownership of objects to match the original database.
 262         By default, <application>pg_restore</application> issues
 263         <command>ALTER OWNER</> or
 264         <command>SET SESSION AUTHORIZATION</command>
 265         statements to set ownership of created schema elements.
 266         These statements will fail unless the initial connection to the
 267         database is made by a superuser
 268         (or the same user that owns all of the objects in the script).
 269         With <option>-O</option>, any user name can be used for the
 270         initial connection, and this user will own all the created objects.
 271        </para>
 272       </listitem>
 273      </varlistentry>
 274
 275      <varlistentry>
 276       <term><option>-P <replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
 277       <term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
 278       <listitem>
 279        <para>
 280         Restore the named function only.  Be careful to spell the function
 281         name and arguments exactly as they appear in the dump file's table
 282         of contents.
 283        </para>
 284       </listitem>
 285      </varlistentry>
 286
 287      <varlistentry>
 288       <term><option>-R</option></term>
 289       <term><option>--no-reconnect</option></term>
 290       <listitem>
 291        <para>
 292         This option is obsolete but still accepted for backwards
 293         compatibility.
 294        </para>
 295       </listitem>
 296      </varlistentry>
 297
 298      <varlistentry>
 299       <term><option>-s</option></term>
 300       <term><option>--schema-only</option></term>
 301       <listitem>
 302        <para>
 303         Restore only the schema (data definitions), not the data (table
 304         contents).  Sequence current values will not be restored, either.
 305         (Do not confuse this with the <option>--schema</> option, which
 306         uses the word <quote>schema</> in a different meaning.)
 307        </para>
 308       </listitem>
 309      </varlistentry>
 310
 311      <varlistentry>
 312       <term><option>-S <replaceable class="parameter">username</replaceable></option></term>
 313       <term><option>--superuser=<replaceable class="parameter">username</replaceable></option></term>
 314       <listitem>
 315        <para>
 316         Specify the superuser user name to use when disabling triggers.
 317         This is only relevant if <option>--disable-triggers</> is used.
 318        </para>
 319       </listitem>
 320      </varlistentry>
 321
 322      <varlistentry>
 323       <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
 324       <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
 325       <listitem>
 326        <para>
 327         Restore definition and/or data of named table only.
 328        </para>
 329       </listitem>
 330      </varlistentry>
 331
 332      <varlistentry>
 333       <term><option>-T <replaceable class="parameter">trigger</replaceable></option></term>
 334       <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
 335       <listitem>
 336        <para>
 337         Restore named trigger only.
 338        </para>
 339       </listitem>
 340      </varlistentry>
 341
 342      <varlistentry>
 343       <term><option>-v</option></term>
 344       <term><option>--verbose</option></term>
 345       <listitem>
 346        <para>
 347         Specifies verbose mode.
 348        </para>
 349       </listitem>
 350      </varlistentry>
 351
 352      <varlistentry>
 353       <term><option>-x</option></term>
 354       <term><option>--no-privileges</option></term>
 355       <term><option>--no-acl</option></term>
 356       <listitem>
 357        <para>
 358         Prevent restoration of access privileges (grant/revoke commands).
 359        </para>
 360       </listitem>
 361      </varlistentry>
 362
 363      <varlistentry>
 364       <term><option>-X disable-triggers</></term>
 365       <term><option>--disable-triggers</></term>
 366       <listitem>
 367        <para>
 368         This option is only relevant when performing a data-only restore.
 369         It instructs <application>pg_restore</application> to execute commands
 370         to temporarily disable triggers on the target tables while
 371         the data is reloaded.  Use this if you have referential
 372         integrity checks or other triggers on the tables that you
 373         do not want to invoke during data reload.
 374        </para>
 375
 376        <para>
 377         Presently, the commands emitted for
 378         <option>--disable-triggers</> must be done as superuser.  So, you
 379         should also specify a superuser name with <option>-S</>, or
 380         preferably run <application>pg_restore</application> as a
 381         <productname>PostgreSQL</> superuser.
 382        </para>
 383       </listitem>
 384      </varlistentry>
 385
 386      <varlistentry>
 387       <term><option>-X use-set-session-authorization</option></term>
 388       <term><option>--use-set-session-authorization</option></term>
 389       <listitem>
 390        <para>
 391         Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
 392         instead of <command>ALTER OWNER</> commands to determine object
 393         ownership.  This makes the dump more standards compatible, but
 394         depending on the history of the objects in the dump, may not restore
 395         properly.
 396        </para>
 397       </listitem>
 398      </varlistentry>
 399
 400      <varlistentry>
 401       <term><option>-X no-data-for-failed-tables</></term>
 402       <listitem>
 403        <para>
 404        By default, table data objects are restored even if the
 405        associated table could not be successfully created (e. g.
 406        because it already exists). With this option, such table
 407        data is silently ignored. This is useful for dumping and
 408        restoring databases with tables which contain auxiliary data
 409        for PostgreSQL extensions (e. g. PostGIS).
 410        </para>
 411       </listitem>
 412      </varlistentry>
 413
 414     </variablelist>
 415    </para>
 416
 417    <para>
 418     <application>pg_restore</application> also accepts
 419     the following command line arguments for connection parameters:
 420
 421     <variablelist>
 422      <varlistentry>
 423       <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
 424       <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
 425       <listitem>
 426        <para>
 427         Specifies the host name of the machine on which the server is
 428         running.  If the value begins with a slash, it is used as the
 429         directory for the Unix domain socket. The default is taken
 430         from the <envar>PGHOST</envar> environment variable, if set,
 431         else a Unix domain socket connection is attempted.
 432        </para>
 433       </listitem>
 434      </varlistentry>
 435
 436      <varlistentry>
 437       <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
 438       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
 439       <listitem>
 440        <para>
 441         Specifies the TCP port or local Unix domain socket file
 442         extension on which the server is listening for connections.
 443         Defaults to the <envar>PGPORT</envar> environment variable, if
 444         set, or a compiled-in default.
 445         </para>
 446       </listitem>
 447      </varlistentry>
 448
 449      <varlistentry>
 450       <term><option>-U <replaceable>username</replaceable></option></term>
 451       <listitem>
 452        <para>
 453         Connect as the given user
 454        </para>
 455       </listitem>
 456      </varlistentry>
 457
 458      <varlistentry>
 459       <term><option>-W</option></term>
 460       <listitem>
 461        <para>
 462         Force a password prompt.  This should happen automatically if
 463         the server requires password authentication.
 464        </para>
 465       </listitem>
 466      </varlistentry>
 467
 468      <varlistentry>
 469       <term><option>-1</option></term>
 470       <term><option>--single-transaction</option></term>
 471       <listitem>
 472        <para>
 473         Execute the restore as a single transaction (that is, wrap the
 474         emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
 475         ensures that either all the commands complete successfully, or no
 476         changes are applied. This option implies
 477         <option>--exit-on-error</>.
 478        </para>
 479       </listitem>
 480      </varlistentry>
 481
 482     </variablelist>
 483    </para>
 484  </refsect1>
 485
 486
 487  <refsect1>
 488   <title>Environment</title>
 489
 490   <variablelist>
 491    <varlistentry>
 492     <term><envar>PGHOST</envar></term>
 493     <term><envar>PGPORT</envar></term>
 494     <term><envar>PGUSER</envar></term>
 495
 496     <listitem>
 497      <para>
 498       Default connection parameters
 499      </para>
 500     </listitem>
 501    </varlistentry>
 502   </variablelist>
 503  </refsect1>
 504
 505
 506  <refsect1 id="app-pgrestore-diagnostics">
 507   <title>Diagnostics</title>
 508
 509   <para>
 510    When a direct database connection is specified using the
 511    <option>-d</option> option, <application>pg_restore</application>
 512    internally executes <acronym>SQL</acronym> statements. If you have
 513    problems running <application>pg_restore</application>, make sure
 514    you are able to select information from the database using, for
 515    example, <xref linkend="app-psql">.
 516   </para>
 517  </refsect1>
 518
 519
 520  <refsect1 id="app-pgrestore-notes">
 521   <title>Notes</title>
 522
 523   <para>
 524    If your installation has any local additions to the
 525    <literal>template1</> database, be careful to load the output of
 526    <application>pg_restore</application> into a truly empty database;
 527    otherwise you are likely to get errors due to duplicate definitions
 528    of the added objects.  To make an empty database without any local
 529    additions, copy from <literal>template0</> not <literal>template1</>, for example:
 530 <programlisting>
 531 CREATE DATABASE foo WITH TEMPLATE template0;
 532 </programlisting>
 533   </para>
 534
 535   <para>
 536    The limitations of <application>pg_restore</application> are detailed below.
 537
 538    <itemizedlist>
 539     <listitem>
 540      <para>
 541       When restoring data to a pre-existing table and the option
 542       <option>--disable-triggers</> is used,
 543       <application>pg_restore</application> emits commands
 544       to disable triggers on user tables before inserting the data then emits commands to
 545       re-enable them after the data has been inserted.  If the restore is stopped in the
 546       middle, the system catalogs may be left in the wrong state.
 547      </para>
 548     </listitem>
 549
 550     <listitem>
 551      <para>
 552       <application>pg_restore</application> will not restore large objects for a single table. If
 553       an archive contains large objects, then all large objects will be restored.
 554      </para>
 555     </listitem>
 556
 557    </itemizedlist>
 558   </para>
 559
 560   <para>
 561    See also the <xref linkend="app-pgdump"> documentation for details on
 562    limitations of <application>pg_dump</application>.
 563   </para>
 564
 565   <para>
 566    Once restored, it is wise to run <command>ANALYZE</> on each
 567    restored table so the optimizer has useful statistics.
 568   </para>
 569
 570  </refsect1>
 571
 572
 573  <refsect1 id="app-pgrestore-examples">
 574   <title>Examples</title>
 575
 576   <para>
 577    To dump a database called <literal>mydb</> to a <filename>tar</filename>
 578    file:
 579
 580 <screen>
 581 <prompt>$</prompt> <userinput>pg_dump -Ft mydb &gt; db.tar</userinput>
 582 </screen>
 583   </para>
 584
 585   <para>
 586    To reload this dump into an
 587    existing database called <literal>newdb</>:
 588
 589 <screen>
 590 <prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
 591 </screen>
 592   </para>
 593
 594   <para>
 595    To reorder database items, it is first necessary to dump the table of
 596    contents of the archive:
 597 <screen>
 598 <prompt>$</prompt> <userinput>pg_restore -l archive.file &gt; archive.list</userinput>
 599 </screen>
 600    The listing file consists of a header and one line for each item, e.g.,
 601 <programlisting>
 602 ;
 603 ; Archive created at Fri Jul 28 22:28:36 2000
 604 ;     dbname: birds
 605 ;     TOC Entries: 74
 606 ;     Compression: 0
 607 ;     Dump Version: 1.4-0
 608 ;     Format: CUSTOM
 609 ;
 610 ;
 611 ; Selected TOC Entries:
 612 ;
 613 2; 145344 TABLE species postgres
 614 3; 145344 ACL species
 615 4; 145359 TABLE nt_header postgres
 616 5; 145359 ACL nt_header
 617 6; 145402 TABLE species_records postgres
 618 7; 145402 ACL species_records
 619 8; 145416 TABLE ss_old postgres
 620 9; 145416 ACL ss_old
 621 10; 145433 TABLE map_resolutions postgres
 622 11; 145433 ACL map_resolutions
 623 12; 145443 TABLE hs_old postgres
 624 13; 145443 ACL hs_old
 625 </programlisting>
 626    Semicolons start a comment, and the numbers at the start of lines refer to the
 627    internal archive ID assigned to each item.
 628   </para>
 629
 630   <para>
 631    Lines in the file can be commented out, deleted, and reordered. For example,
 632 <programlisting>
 633 10; 145433 TABLE map_resolutions postgres
 634 ;2; 145344 TABLE species postgres
 635 ;4; 145359 TABLE nt_header postgres
 636 6; 145402 TABLE species_records postgres
 637 ;8; 145416 TABLE ss_old postgres
 638 </programlisting>
 639    could be used as input to <application>pg_restore</application> and would only restore
 640    items 10 and 6, in that order:
 641 <screen>
 642 <prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
 643 </screen>
 644   </para>
 645
 646  </refsect1>
 647
 648  <refsect1>
 649   <title>History</title>
 650
 651   <para>
 652    The <application>pg_restore</application> utility first appeared in
 653    <productname>PostgreSQL</productname> 7.1.
 654   </para>
 655  </refsect1>
 656
 657  <refsect1>
 658   <title>See Also</title>
 659
 660   <simplelist type="inline">
 661    <member><xref linkend="app-pgdump"></member>
 662    <member><xref linkend="app-pg-dumpall"></member>
 663    <member><xref linkend="app-psql"></member>
 664    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
 665   </simplelist>
 666  </refsect1>
 667 </refentry>
 668
 669 <!-- Keep this comment at the end of the file
 670 Local variables:
 671 mode: sgml
 672 sgml-omittag:nil
 673 sgml-shorttag:t
 674 sgml-minimize-attributes:nil
 675 sgml-always-quote-attributes:t
 676 sgml-indent-step:1
 677 sgml-indent-data:t
 678 sgml-parent-document:nil
 679 sgml-default-dtd-file:"../reference.ced"
 680 sgml-exposed-tags:nil
 681 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 682 sgml-local-ecat-files:nil
 683 End:
 684 -->