head	1.88;
access;
symbols
	REL9_0_0:1.87.2.1
	REL9_1_ALPHA1:1.88
	REL9_0_RC1:1.87.2.1
	REL9_0_BETA4:1.87
	REL9_0_STABLE:1.87.0.2
	REL9_0_BETA3:1.87
	REL9_0_BETA2:1.87
	REL7_4_29:1.43
	REL8_0_25:1.49.4.1
	REL8_1_21:1.56
	REL8_2_17:1.64.2.2
	REL8_3_11:1.72
	REL8_4_4:1.81.2.1
	REL9_0_BETA1:1.86
	REL9_0_ALPHA5_BRANCH:1.86.0.2
	REL9_0_ALPHA5:1.86
	REL7_4_28:1.43
	REL8_0_24:1.49.4.1
	REL8_1_20:1.56
	REL8_2_16:1.64.2.2
	REL8_3_10:1.72
	REL8_4_3:1.81.2.1
	REL9_0_ALPHA4:1.84
	REL9_0_ALPHA4_BRANCH:1.84.0.2
	REL8_5_ALPHA3:1.82
	REL8_5_ALPHA3_BRANCH:1.82.0.6
	REL7_4_27:1.43
	REL8_0_23:1.49.4.1
	REL8_1_19:1.56
	REL8_2_15:1.64.2.2
	REL8_3_9:1.72
	REL8_4_2:1.81.2.1
	REL8_5_ALPHA2:1.82
	REL8_5_ALPHA2_BRANCH:1.82.0.4
	REL7_4_26:1.43
	REL8_0_22:1.49.4.1
	REL8_1_18:1.56
	REL8_2_14:1.64.2.2
	REL8_3_8:1.72
	REL8_4_1:1.81.2.1
	REL8_5_ALPHA1:1.82
	REL8_5_ALPHA1_BRANCH:1.82.0.2
	REL8_4_STABLE:1.81.0.2
	REL8_4_0:1.81
	REL8_4_RC2:1.81
	REL8_4_RC1:1.81
	REL8_4_BETA2:1.81
	REL8_4_BETA1:1.81
	REL7_4_25:1.43
	REL8_0_21:1.49.4.1
	REL8_1_17:1.56
	REL8_2_13:1.64.2.2
	REL8_3_7:1.72
	REL7_4_24:1.43
	REL8_0_20:1.49.4.1
	REL8_1_16:1.56
	REL8_2_12:1.64.2.2
	REL8_3_6:1.72
	REL7_4_23:1.43
	REL8_0_19:1.49.4.1
	REL8_1_15:1.56
	REL8_2_11:1.64.2.2
	REL8_3_5:1.72
	REL7_4_22:1.43
	REL8_0_18:1.49.4.1
	REL8_1_14:1.56
	REL8_2_10:1.64.2.2
	REL8_3_4:1.72
	REL7_4_21:1.43
	REL8_0_17:1.49.4.1
	REL8_1_13:1.56
	REL8_2_9:1.64.2.2
	REL8_3_3:1.72
	REL7_4_20:1.43
	REL8_0_16:1.49.4.1
	REL8_1_12:1.56
	REL8_2_8:1.64.2.2
	REL8_3_2:1.72
	REL8_2_7:1.64.2.2
	REL8_3_1:1.72
	REL8_3_STABLE:1.72.0.2
	REL8_3_0:1.72
	REL8_3_RC2:1.72
	REL7_3_21:1.31.2.1
	REL7_4_19:1.43
	REL8_0_15:1.49.4.1
	REL8_1_11:1.56
	REL8_2_6:1.64.2.2
	REL8_3_RC1:1.72
	REL8_3_BETA4:1.71
	REL8_3_BETA3:1.71
	REL8_3_BETA2:1.71
	REL8_3_BETA1:1.71
	REL7_3_20:1.31.2.1
	REL7_4_18:1.43
	REL8_0_14:1.49.4.1
	REL8_1_10:1.56
	REL8_2_5:1.64.2.2
	REL7_3_19:1.31.2.1
	REL7_4_17:1.43
	REL8_0_13:1.49.4.1
	REL8_1_9:1.56
	REL8_2_4:1.64.2.2
	REL8_0_12:1.49.4.1
	REL8_1_8:1.56
	REL8_2_3:1.64
	REL7_3_18:1.31.2.1
	REL7_4_16:1.43
	REL8_0_11:1.49.4.1
	REL8_1_7:1.56
	REL8_2_2:1.64
	REL8_0_10:1.49.4.1
	REL8_1_6:1.56
	REL8_2_1:1.64
	REL7_4_15:1.43
	REL7_3_17:1.31.2.1
	REL8_2_STABLE:1.64.0.2
	REL8_2_0:1.64
	REL8_2_RC1:1.63
	REL8_2_BETA3:1.63
	REL8_2_BETA2:1.63
	REL8_1_5:1.56
	REL8_0_9:1.49.4.1
	REL7_4_14:1.43
	REL7_3_16:1.31.2.1
	REL8_2_BETA1:1.61
	REL7_3_15:1.31.2.1
	REL7_4_13:1.43
	REL8_0_8:1.49.4.1
	REL8_1_4:1.56
	REL7_3_14:1.31.2.1
	REL7_4_12:1.43
	REL8_0_7:1.49.4.1
	REL8_1_3:1.56
	REL7_3_13:1.31.2.1
	REL7_4_11:1.43
	REL8_0_6:1.49.4.1
	REL8_1_2:1.56
	REL7_3_12:1.31.2.1
	REL7_4_10:1.43
	REL8_0_5:1.49.4.1
	REL8_1_1:1.56
	REL8_1_STABLE:1.56.0.2
	REL8_1_0:1.56
	REL8_1_0RC1:1.55
	REL8_1_0BETA4:1.55
	REL8_1_0BETA3:1.55
	REL7_3_11:1.31.2.1
	REL7_4_9:1.43
	REL8_0_4:1.49.4.1
	REL8_1_0BETA2:1.55
	REL8_1_0BETA1:1.55
	REL7_2_8:1.22
	REL7_3_10:1.31.2.1
	REL7_4_8:1.43
	REL8_0_3:1.49.4.1
	REL8_0_2:1.49.4.1
	REL7_2_7:1.22
	REL7_3_9:1.31.2.1
	REL7_4_7:1.43
	REL8_0_1:1.49.4.1
	REL8_0_STABLE:1.49.0.4
	REL8_0_0:1.49.0.2
	REL8_0_0RC5:1.49
	REL8_0_0RC4:1.49
	REL8_0_0RC3:1.48
	REL8_0_0RC2:1.48
	REL8_0_0RC1:1.48
	REL8_0_0BETA5:1.48
	REL8_0_0BETA4:1.48
	REL7_4_6:1.43
	REL7_3_8:1.31.2.1
	REL7_2_6:1.22
	REL8_0_0BETA3:1.48
	REL8_0_0BETA2:1.48
	REL7_2_5:1.22
	REL7_4_5:1.43
	REL7_3_7:1.31.2.1
	REL7_4_4:1.43
	REL8_0_0BETA1:1.47
	REL7_4_3:1.43
	REL7_4_2:1.43
	REL7_3_6:1.31.2.1
	REL7_4_1:1.43
	REL7_3_5:1.31.2.1
	REL7_4:1.43
	REL7_4_RC2:1.43
	REL7_4_STABLE:1.43.0.2
	REL7_4_RC1:1.43
	REL7_4_BETA5:1.43
	REL7_4_BETA4:1.43
	REL7_4_BETA3:1.42
	REL7_4_BETA2:1.39
	WIN32_DEV:1.39.0.2
	REL7_4_BETA1:1.39
	REL7_3_4:1.31.2.1
	REL7_3_2:1.31.2.1
	REL7_2_4:1.22
	REL7_3_STABLE:1.31.0.2
	REL7_2_3:1.22
	REL7_2_STABLE:1.22.0.2
	REL7_2:1.21
	REL7_2_RC2:1.21
	REL7_2_RC1:1.21
	REL7_2_BETA5:1.21
	REL7_2_BETA4:1.21
	REL7_2_BETA3:1.19
	REL7_2_BETA2:1.18
	REL7_2_BETA1:1.18
	REL7_1_2:1.10
	REL7_1_STABLE:1.10.0.2
	REL7_1_BETA:1.5
	REL7_1_BETA3:1.6
	REL7_1_BETA2:1.6
	REL7_1:1.10;
locks; strict;
comment	@# @;


1.88
date	2010.08.17.04.37.21;	author petere;	state Exp;
branches;
next	1.87;

1.87
date	2010.05.15.18.11.07;	author tgl;	state Exp;
branches
	1.87.2.1;
next	1.86;

1.86
date	2010.02.24.16.27.40;	author momjian;	state Exp;
branches;
next	1.85;

1.85
date	2010.02.23.00.21.19;	author momjian;	state Exp;
branches;
next	1.84;

1.84
date	2010.02.19.14.36.45;	author momjian;	state Exp;
branches;
next	1.83;

1.83
date	2010.02.19.03.50.03;	author momjian;	state Exp;
branches;
next	1.82;

1.82
date	2009.08.07.20.54.31;	author alvherre;	state Exp;
branches;
next	1.81;

1.81
date	2009.03.20.09.21.08;	author petere;	state Exp;
branches
	1.81.2.1;
next	1.80;

1.80
date	2009.02.26.16.02.37;	author petere;	state Exp;
branches;
next	1.79;

1.79
date	2009.02.07.14.31.30;	author momjian;	state Exp;
branches;
next	1.78;

1.78
date	2009.02.02.20.07.36;	author adunstan;	state Exp;
branches;
next	1.77;

1.77
date	2009.01.05.16.54.36;	author tgl;	state Exp;
branches;
next	1.76;

1.76
date	2008.09.07.19.12.57;	author tgl;	state Exp;
branches;
next	1.75;

1.75
date	2008.04.13.03.49.21;	author tgl;	state Exp;
branches;
next	1.74;

1.74
date	2008.03.26.16.34.47;	author tgl;	state Exp;
branches;
next	1.73;

1.73
date	2008.03.20.17.36.57;	author tgl;	state Exp;
branches;
next	1.72;

1.72
date	2007.12.11.19.57.32;	author tgl;	state Exp;
branches
	1.72.2.1;
next	1.71;

1.71
date	2007.05.15.19.13.55;	author neilc;	state Exp;
branches;
next	1.70;

1.70
date	2007.03.26.17.23.37;	author tgl;	state Exp;
branches;
next	1.69;

1.69
date	2007.02.20.18.10.58;	author momjian;	state Exp;
branches;
next	1.68;

1.68
date	2007.02.20.15.01.17;	author momjian;	state Exp;
branches;
next	1.67;

1.67
date	2007.02.01.04.39.33;	author neilc;	state Exp;
branches;
next	1.66;

1.66
date	2007.02.01.00.28.19;	author momjian;	state Exp;
branches;
next	1.65;

1.65
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.64;

1.64
date	2006.11.26.18.11.11;	author tgl;	state Exp;
branches
	1.64.2.1;
next	1.63;

1.63
date	2006.10.14.23.07.22;	author tgl;	state Exp;
branches;
next	1.62;

1.62
date	2006.10.07.20.59.04;	author petere;	state Exp;
branches;
next	1.61;

1.61
date	2006.09.16.00.30.19;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	2006.08.01.18.21.44;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	2006.03.17.16.02.47;	author petere;	state Exp;
branches;
next	1.58;

1.58
date	2006.02.13.21.29.08;	author tgl;	state Exp;
branches;
next	1.57;

1.57
date	2006.02.12.04.04.32;	author momjian;	state Exp;
branches;
next	1.56;

1.56
date	2005.11.01.21.09.50;	author tgl;	state Exp;
branches
	1.56.2.1;
next	1.55;

1.55
date	2005.07.27.13.42.01;	author neilc;	state Exp;
branches;
next	1.54;

1.54
date	2005.07.25.22.12.31;	author tgl;	state Exp;
branches;
next	1.53;

1.53
date	2005.06.21.20.45.43;	author tgl;	state Exp;
branches;
next	1.52;

1.52
date	2005.06.09.17.56.51;	author momjian;	state Exp;
branches;
next	1.51;

1.51
date	2005.05.29.03.32.18;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2005.01.23.00.30.31;	author momjian;	state Exp;
branches;
next	1.49;

1.49
date	2005.01.04.03.58.16;	author tgl;	state Exp;
branches
	1.49.4.1;
next	1.48;

1.48
date	2004.08.20.04.20.22;	author momjian;	state Exp;
branches;
next	1.47;

1.47
date	2004.07.13.02.59.49;	author momjian;	state Exp;
branches;
next	1.46;

1.46
date	2004.02.17.09.07.16;	author neilc;	state Exp;
branches;
next	1.45;

1.45
date	2003.12.06.03.00.10;	author tgl;	state Exp;
branches;
next	1.44;

1.44
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.43;

1.43
date	2003.09.23.22.48.53;	author tgl;	state Exp;
branches
	1.43.2.1;
next	1.42;

1.42
date	2003.09.11.21.42.20;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2003.08.31.17.32.24;	author petere;	state Exp;
branches;
next	1.40;

1.40
date	2003.08.28.20.44.02;	author tgl;	state Exp;
branches;
next	1.39;

1.39
date	2003.06.11.16.29.42;	author tgl;	state Exp;
branches
	1.39.2.1;
next	1.38;

1.38
date	2003.03.25.16.15.43;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2003.03.24.14.32.51;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2003.03.18.00.02.11;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2003.01.19.00.13.31;	author momjian;	state Exp;
branches;
next	1.34;

1.34
date	2003.01.06.18.53.24;	author petere;	state Exp;
branches;
next	1.33;

1.33
date	2002.11.21.23.34.43;	author petere;	state Exp;
branches;
next	1.32;

1.32
date	2002.11.15.03.11.18;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2002.10.11.23.03.48;	author petere;	state Exp;
branches
	1.31.2.1;
next	1.30;

1.30
date	2002.08.10.16.57.31;	author petere;	state Exp;
branches;
next	1.29;

1.29
date	2002.07.28.15.22.20;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2002.07.13.00.55.53;	author momjian;	state Exp;
branches;
next	1.27;

1.27
date	2002.07.10.02.57.31;	author momjian;	state Exp;
branches;
next	1.26;

1.26
date	2002.07.04.03.04.54;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	2002.05.10.22.36.26;	author tgl;	state Exp;
branches;
next	1.24;

1.24
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.23;

1.23
date	2002.03.22.19.20.42;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2002.02.11.00.14.10;	author tgl;	state Exp;
branches;
next	1.21;

1.21
date	2001.11.28.20.49.10;	author petere;	state Exp;
branches;
next	1.20;

1.20
date	2001.11.26.23.09.21;	author tgl;	state Exp;
branches;
next	1.19;

1.19
date	2001.11.19.03.58.25;	author tgl;	state Exp;
branches;
next	1.18;

1.18
date	2001.10.23.22.11.22;	author tgl;	state Exp;
branches;
next	1.17;

1.17
date	2001.09.21.21.58.30;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2001.09.13.15.55.24;	author petere;	state Exp;
branches;
next	1.15;

1.15
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.14;

1.14
date	2001.08.22.20.23.23;	author petere;	state Exp;
branches;
next	1.13;

1.13
date	2001.08.12.19.02.39;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2001.05.17.21.50.18;	author petere;	state Exp;
branches;
next	1.11;

1.11
date	2001.05.17.21.12.48;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2001.03.17.16.27.31;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2001.03.06.18.55.57;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2001.03.06.05.22.50;	author pjw;	state Exp;
branches;
next	1.7;

1.7
date	2001.03.05.18.42.57;	author momjian;	state Exp;
branches;
next	1.6;

1.6
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.5;

1.5
date	2000.11.30.23.20.50;	author tgl;	state Exp;
branches;
next	1.4;

1.4
date	2000.11.22.01.41.13;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	2000.11.13.23.57.20;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	2000.10.20.13.44.39;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	2000.10.12.14.09.37;	author pjw;	state Exp;
branches;
next	;

1.31.2.1
date	2002.11.21.23.31.58;	author petere;	state Exp;
branches;
next	;

1.39.2.1
date	2003.09.07.04.36.46;	author momjian;	state Exp;
branches;
next	;

1.43.2.1
date	2010.05.15.18.11.41;	author tgl;	state Exp;
branches;
next	;

1.49.4.1
date	2005.01.23.00.37.56;	author momjian;	state Exp;
branches;
next	1.49.4.2;

1.49.4.2
date	2010.05.15.18.11.35;	author tgl;	state Exp;
branches;
next	;

1.56.2.1
date	2010.05.15.18.11.30;	author tgl;	state Exp;
branches;
next	;

1.64.2.1
date	2007.02.20.18.11.17;	author momjian;	state Exp;
branches;
next	1.64.2.2;

1.64.2.2
date	2007.03.26.17.23.45;	author tgl;	state Exp;
branches;
next	1.64.2.3;

1.64.2.3
date	2010.05.15.18.11.25;	author tgl;	state Exp;
branches;
next	;

1.72.2.1
date	2010.05.15.18.11.19;	author tgl;	state Exp;
branches;
next	;

1.81.2.1
date	2009.08.07.20.55.05;	author alvherre;	state Exp;
branches;
next	1.81.2.2;

1.81.2.2
date	2010.05.15.18.11.13;	author tgl;	state Exp;
branches;
next	;

1.87.2.1
date	2010.08.17.04.37.19;	author petere;	state Exp;
branches;
next	;


desc
@@


1.88
log
@Spell and markup checking
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.87 2010/05/15 18:11:07 tgl Exp $ -->

<refentry id="APP-PGRESTORE">
 <refmeta>
  <refentrytitle>pg_restore</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_restore</refname>

  <refpurpose>
   restore a <productname>PostgreSQL</productname> database from an
   archive file created by <application>pg_dump</application>
  </refpurpose>
 </refnamediv>

 <indexterm zone="app-pgrestore">
  <primary>pg_restore</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_restore</command>
   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg><replaceable>filename</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="app-pgrestore-description">
  <title>Description</title>

  <para>
   <application>pg_restore</application> is a utility for restoring a
   <productname>PostgreSQL</productname> database from an archive
   created by <xref linkend="app-pgdump"> in one of the non-plain-text
   formats.  It will issue the commands necessary to reconstruct the
   database to the state it was in at the time it was saved.  The
   archive files also allow <application>pg_restore</application> to
   be selective about what is restored, or even to reorder the items
   prior to being restored. The archive files are designed to be
   portable across architectures.
  </para>

  <para>
   <application>pg_restore</application> can operate in two modes.
   If a database name is specified, <application>pg_restore</application>
   connects to that database and restores archive contents directly into
   the database.  Otherwise, a script containing the SQL
   commands necessary to rebuild the database is created and written
   to a file or standard output.  This script output is equivalent to
   the plain text output format of <application>pg_dump</application>.
   Some of the options controlling the output are therefore analogous to
   <application>pg_dump</application> options.
  </para>

  <para>
   Obviously, <application>pg_restore</application> cannot restore information
   that is not present in the archive file.  For instance, if the
   archive was made using the <quote>dump data as
   <command>INSERT</command> commands</quote> option,
   <application>pg_restore</application> will not be able to load the data
   using <command>COPY</command> statements.
  </para>
 </refsect1>

 <refsect1 id="app-pgrestore-options">
  <title>Options</title>

   <para>
    <application>pg_restore</application> accepts the following command
    line arguments.

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">filename</replaceable></term>
      <listitem>
       <para>
       Specifies the location of the archive file to be restored.
       If not specified, the standard input is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-a</option></term>
      <term><option>--data-only</option></term>
      <listitem>
       <para>
        Restore only the data, not the schema (data definitions).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c</option></term>
      <term><option>--clean</option></term>
      <listitem>
       <para>
        Clean (drop) database objects before recreating them.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-C</option></term>
      <term><option>--create</option></term>
      <listitem>
       <para>
        Create the database before restoring into it.  (When this
        option is used, the database named with <option>-d</option> is
        used only to issue the initial <command>CREATE DATABASE</>
        command.  All data is restored into the database name that
        appears in the archive.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
      <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term>
      <listitem>
       <para>
        Connect to database <replaceable
        class="parameter">dbname</replaceable> and restore directly
        into the database.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-e</option></term>
      <term><option>--exit-on-error</option></term>
      <listitem>
       <para>
        Exit if an error is encountered while sending SQL commands to
        the database. The default is to continue and to display a count of
        errors at the end of the restoration.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-f <replaceable>filename</replaceable></option></term>
      <term><option>--file=<replaceable>filename</replaceable></option></term>
      <listitem>
       <para>
        Specify output file for generated script, or for the listing
        when used with <option>-l</option>. Default is the standard
        output.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
      <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
      <listitem>
       <para>
        Specify format of the archive.  It is not necessary to specify
        the format, since <application>pg_restore</application> will
        determine the format automatically. If specified, it can be
        one of the following:

       <variablelist>
        <varlistentry>
         <term><literal>t</></term>
         <term><literal>tar</></term>
         <listitem>
          <para>
           The archive is a <command>tar</command> archive.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>c</></term>
         <term><literal>custom</></term>
         <listitem>
          <para>
           The archive is in the custom format of
           <application>pg_dump</application>.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</option></term>
      <term><option>--ignore-version</option></term>
      <listitem>
       <para>
        A deprecated option that is now ignored.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-I <replaceable class="parameter">index</replaceable></option></term>
      <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
      <listitem>
       <para>
        Restore definition of named index only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-j <replaceable class="parameter">number-of-jobs</replaceable></option></term>
      <term><option>--jobs=<replaceable class="parameter">number-of-jobs</replaceable></option></term>
      <listitem>
       <para>
        Run the most time-consuming parts
        of <application>pg_restore</> &mdash; those which load data,
        create indexes, or create constraints &mdash; using multiple
        concurrent jobs.  This option can dramatically reduce the time
        to restore a large database to a server running on a
        multiprocessor machine.
       </para>

       <para>
        Each job is one process or one thread, depending on the
        operating system, and uses a separate connection to the
        server.
       </para>

       <para>
        The optimal value for this option depends on the hardware
        setup of the server, of the client, and of the network.
        Factors include the number of CPU cores and the disk setup.  A
        good place to start is the number of CPU cores on the server,
        but values larger than that can also lead to faster restore
        times in many cases.  Of course, values that are too high will
        lead to decreased performance because of thrashing.
       </para>

       <para>
        Only the custom archive format is supported with this option.
        The input file must be a regular file (not, for example, a
        pipe).  This option is ignored when emitting a script rather
        than connecting directly to a database server.  Also, multiple
        jobs cannot be used together with the
        option <option>--single-transaction</option>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-l</option></term>
      <term><option>--list</option></term>
      <listitem>
       <para>
        List the contents of the archive. The output of this operation
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-L <replaceable class="parameter">list-file</replaceable></option></term>
      <term><option>--use-list=<replaceable class="parameter">list-file</replaceable></option></term>
      <listitem>
       <para>
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-n <replaceable class="parameter">namespace</replaceable></option></term>
      <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
      <listitem>
       <para>
        Restore only objects that are in the named schema.  This can be
        combined with the <option>-t</option> option to restore just a
        specific table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-O</option></term>
      <term><option>--no-owner</option></term>
      <listitem>
       <para>
        Do not output commands to set
        ownership of objects to match the original database.
        By default, <application>pg_restore</application> issues
        <command>ALTER OWNER</> or
        <command>SET SESSION AUTHORIZATION</command>
        statements to set ownership of created schema elements.
        These statements will fail unless the initial connection to the
        database is made by a superuser
        (or the same user that owns all of the objects in the script).
        With <option>-O</option>, any user name can be used for the
        initial connection, and this user will own all the created objects.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--no-tablespaces</option></term>
      <listitem>
       <para>
        Do not output commands to select tablespaces.
        With this option, all objects will be created in whichever
        tablespace is the default during restore.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-P <replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
      <term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
      <listitem>
       <para>
        Restore the named function only.  Be careful to spell the function
        name and arguments exactly as they appear in the dump file's table
        of contents.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-R</option></term>
      <term><option>--no-reconnect</option></term>
      <listitem>
       <para>
        This option is obsolete but still accepted for backwards
        compatibility.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s</option></term>
      <term><option>--schema-only</option></term>
      <listitem>
       <para>
        Restore only the schema (data definitions), not the data (table
        contents).  Current sequence values will not be restored, either.
        (Do not confuse this with the <option>--schema</> option, which
        uses the word <quote>schema</> in a different meaning.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-S <replaceable class="parameter">username</replaceable></option></term>
      <term><option>--superuser=<replaceable class="parameter">username</replaceable></option></term>
      <listitem>
       <para>
        Specify the superuser user name to use when disabling triggers.
        This is only relevant if <option>--disable-triggers</> is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
      <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
      <listitem>
       <para>
        Restore definition and/or data of named table only.  This can be
        combined with the <option>-n</option> option to specify a schema.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-T <replaceable class="parameter">trigger</replaceable></option></term>
      <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
      <listitem>
       <para>
        Restore named trigger only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</option></term>
      <term><option>--verbose</option></term>
      <listitem>
       <para>
        Specifies verbose mode.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-V</></term>
       <term><option>--version</></term>
       <listitem>
       <para>
       Print the <application>pg_restore</application> version and exit.
       </para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-x</option></term>
      <term><option>--no-privileges</option></term>
      <term><option>--no-acl</option></term>
      <listitem>
       <para>
        Prevent restoration of access privileges (grant/revoke commands).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--disable-triggers</></term>
      <listitem>
       <para>
        This option is only relevant when performing a data-only restore.
        It instructs <application>pg_restore</application> to execute commands
        to temporarily disable triggers on the target tables while
        the data is reloaded.  Use this if you have referential
        integrity checks or other triggers on the tables that you
        do not want to invoke during data reload.
       </para>

       <para>
        Presently, the commands emitted for
        <option>--disable-triggers</> must be done as superuser.  So, you
        should also specify a superuser name with <option>-S</>, or
        preferably run <application>pg_restore</application> as a
        <productname>PostgreSQL</> superuser.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--use-set-session-authorization</option></term>
      <listitem>
       <para>
        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
        instead of <command>ALTER OWNER</> commands to determine object
        ownership.  This makes the dump more standards-compatible, but
        depending on the history of the objects in the dump, might not restore
        properly.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--no-data-for-failed-tables</option></term>
      <listitem>
       <para>
        By default, table data is restored even if the creation command
        for the table failed (e.g., because it already exists).
        With this option, data for such a table is skipped.
        This behavior is useful if the target database already
        contains the desired table contents.  For example,
        auxiliary tables for <productname>PostgreSQL</> extensions
        such as <productname>PostGIS</> might already be loaded in
        the target database; specifying this option prevents duplicate
        or obsolete data from being loaded into them.
       </para>

       <para>
        This option is effective only when restoring directly into a
        database, not when producing SQL script output.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-1</option></term>
      <term><option>--single-transaction</option></term>
      <listitem>
       <para>
        Execute the restore as a single transaction (that is, wrap the
        emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
        ensures that either all the commands complete successfully, or no
        changes are applied. This option implies
        <option>--exit-on-error</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-?</></term>
       <term><option>--help</></term>
       <listitem>
       <para>
       Show help about <application>pg_restore</application> command line
       arguments, and exit.
       </para>
       </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    <application>pg_restore</application> also accepts
    the following command line arguments for connection parameters:

    <variablelist>
     <varlistentry>
      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
      <listitem>
       <para>
        Specifies the host name of the machine on which the server is
        running.  If the value begins with a slash, it is used as the
        directory for the Unix domain socket. The default is taken
        from the <envar>PGHOST</envar> environment variable, if set,
        else a Unix domain socket connection is attempted.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
      <listitem>
       <para>
        Specifies the TCP port or local Unix domain socket file
        extension on which the server is listening for connections.
        Defaults to the <envar>PGPORT</envar> environment variable, if
        set, or a compiled-in default.
        </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-U <replaceable>username</replaceable></option></term>
      <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
      <listitem>
       <para>
        User name to connect as.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-w</></term>
      <term><option>--no-password</></term>
      <listitem>
       <para>
        Never issue a password prompt.  If the server requires
        password authentication and a password is not available by
        other means such as a <filename>.pgpass</filename> file, the
        connection attempt will fail.  This option can be useful in
        batch jobs and scripts where no user is present to enter a
        password.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</option></term>
      <term><option>--password</option></term>
      <listitem>
       <para>
        Force <application>pg_restore</application> to prompt for a
        password before connecting to a database.
       </para>

       <para>
        This option is never essential, since
        <application>pg_restore</application> will automatically prompt
        for a password if the server demands password authentication.
        However, <application>pg_restore</application> will waste a
        connection attempt finding out that the server wants a password.
        In some cases it is worth typing <option>-W</> to avoid the extra
        connection attempt.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--role=<replaceable class="parameter">rolename</replaceable></option></term>
      <listitem>
       <para>
        Specifies a role name to be used to perform the restore.
        This option causes <application>pg_restore</> to issue a
        <command>SET ROLE</> <replaceable class="parameter">rolename</>
        command after connecting to the database. It is useful when the
        authenticated user (specified by <option>-U</>) lacks privileges
        needed by <application>pg_restore</>, but can switch to a role with
        the required rights.  Some installations have a policy against
        logging in directly as a superuser, and use of this option allows
        restores to be performed without violating the policy.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGHOST</envar></term>
    <term><envar>PGOPTIONS</envar></term>
    <term><envar>PGPORT</envar></term>
    <term><envar>PGUSER</envar></term>

    <listitem>
     <para>
      Default connection parameters
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   This utility, like most other <productname>PostgreSQL</> utilities,
   also uses the environment variables supported by <application>libpq</>
   (see <xref linkend="libpq-envars">).
  </para>

 </refsect1>


 <refsect1 id="app-pgrestore-diagnostics">
  <title>Diagnostics</title>

  <para>
   When a direct database connection is specified using the
   <option>-d</option> option, <application>pg_restore</application>
   internally executes <acronym>SQL</acronym> statements. If you have
   problems running <application>pg_restore</application>, make sure
   you are able to select information from the database using, for
   example, <xref linkend="app-psql">.  Also, any default connection
   settings and environment variables used by the
   <application>libpq</application> front-end library will apply.
  </para>
 </refsect1>


 <refsect1 id="app-pgrestore-notes">
  <title>Notes</title>

  <para>
   If your installation has any local additions to the
   <literal>template1</> database, be careful to load the output of
   <application>pg_restore</application> into a truly empty database;
   otherwise you are likely to get errors due to duplicate definitions
   of the added objects.  To make an empty database without any local
   additions, copy from <literal>template0</> not <literal>template1</>, for example:
<programlisting>
CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting>
  </para>

  <para>
   The limitations of <application>pg_restore</application> are detailed below.

   <itemizedlist>
    <listitem>
     <para>
      When restoring data to a pre-existing table and the option
      <option>--disable-triggers</> is used,
      <application>pg_restore</application> emits commands
      to disable triggers on user tables before inserting the data, then emits commands to
      re-enable them after the data has been inserted.  If the restore is stopped in the
      middle, the system catalogs might be left in the wrong state.
     </para>
    </listitem>

    <listitem>
     <para>
      <application>pg_restore</application> cannot restore large objects
      selectively;  for instance, only those for a specific table.  If
      an archive contains large objects, then all large objects will be
      restored, or none of them if they are excluded via <option>-L</option>,
      <option>-t</option>, or other options.
     </para>
    </listitem>

   </itemizedlist>
  </para>

  <para>
   See also the <xref linkend="app-pgdump"> documentation for details on
   limitations of <application>pg_dump</application>.
  </para>

  <para>
   Once restored, it is wise to run <command>ANALYZE</> on each
   restored table so the optimizer has useful statistics; see
   <xref linkend="vacuum-for-statistics"> and
   <xref linkend="autovacuum"> for more information.
  </para>

 </refsect1>


 <refsect1 id="app-pgrestore-examples">
  <title>Examples</title>

  <para>
   Assume we have dumped a database called <literal>mydb</> into a
   custom-format dump file:

<screen>
<prompt>$</prompt> <userinput>pg_dump -Fc mydb &gt; db.dump</userinput>
</screen>
  </para>

  <para>
   To drop the database and recreate it from the dump:

<screen>
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
<prompt>$</prompt> <userinput>pg_restore -C -d postgres db.dump</userinput>
</screen>

   The database named in the <option>-d</> switch can be any database existing
   in the cluster; <application>pg_restore</> only uses it to issue the
   <command>CREATE DATABASE</> command for <literal>mydb</>.  With
   <option>-C</>, data is always restored into the database name that appears
   in the dump file.
  </para>

  <para>
   To reload the dump into a new database called <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>createdb -T template0 newdb</userinput>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput>
</screen>

   Notice we don't use <option>-C</>, and instead connect directly to the
   database to be restored into.  Also note that we clone the new database
   from <literal>template0</> not <literal>template1</>, to ensure it is
   initially empty.
  </para>

  <para>
   To reorder database items, it is first necessary to dump the table of
   contents of the archive:
<screen>
<prompt>$</prompt> <userinput>pg_restore -l db.dump &gt; db.list</userinput>
</screen>
   The listing file consists of a header and one line for each item, e.g.:
<programlisting>
;
; Archive created at Mon Sep 14 13:55:39 2009
;     dbname: DBDEMOS
;     TOC Entries: 81
;     Compression: 9
;     Dump Version: 1.10-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 8.3.5
;     Dumped by pg_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha
</programlisting>
   Semicolons start a comment, and the numbers at the start of lines refer to the
   internal archive ID assigned to each item.
  </para>

  <para>
   Lines in the file can be commented out, deleted, and reordered. For example:
<programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
   could be used as input to <application>pg_restore</application> and would only restore
   items 10 and 6, in that order:
<screen>
<prompt>$</prompt> <userinput>pg_restore -L db.list db.dump</userinput>
</screen>
  </para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-pgdump"></member>
   <member><xref linkend="app-pg-dumpall"></member>
   <member><xref linkend="app-psql"></member>
  </simplelist>
 </refsect1>
</refentry>
@


1.87
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.86 2010/02/24 16:27:40 momjian Exp $ -->
d224 1
a224 1
        multi-processor machine.
@


1.87.2.1
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.87 2010/05/15 18:11:07 tgl Exp $ -->
d224 1
a224 1
        multiprocessor machine.
@


1.86
log
@Document that pg_restore -t can use -n for its schema qualification.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.85 2010/02/23 00:21:19 momjian Exp $ -->
d50 2
a51 1
   If a database name is specified, the archive is restored directly into
d54 1
a54 1
   to a file or standard output.  The script output is equivalent to
d174 1
a174 4
           The archive is a <command>tar</command> archive. Using this
           archive format allows reordering and/or exclusion of schema
           elements at the time the database is restored. It is also
           possible to limit which data is reloaded at restore time.
d185 1
a185 4
           <application>pg_dump</application>. This is the most
           flexible format in that it allows reordering of data load
           as well as schema elements.  This format is also compressed
           by default.
d260 3
a262 2
        can be used with the <option>-L</option> option to restrict
        and reorder the items that are restored.
d272 12
a283 5
        Restore elements in <replaceable class="PARAMETER">
        list-file</replaceable> only, and in the
        order they appear in the file. Lines can be moved and can also
        be commented out by placing a <literal>;</literal> at the
        start of the line.  (See below for examples.)
@


1.85
log
@Update pg_restore documentation to show new pg_restore custom listing
format.

Pavel Golub
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.84 2010/02/19 14:36:45 momjian Exp $ -->
d380 2
a381 1
        Restore definition and/or data of named table only.
@


1.84
log
@Document --version and --help options for all client applications (they
all support it).

Per report from Josh Kupershmidt
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.83 2010/02/19 03:50:03 momjian Exp $ -->
d762 5
a766 5
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: mydb
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
d768 4
d776 5
a780 12
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
@


1.83
log
@First pass over client applications documentation proofreading.

gabrielle
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.82 2009/08/07 20:54:31 alvherre Exp $ -->
d406 10
d497 11
@


1.82
log
@Document that autovacuum may run ANALYZE
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.81 2009/03/20 09:21:08 petere Exp $ -->
d26 1
d245 1
a245 1
        lead to decreasing performance because of thrashing.
d357 1
a357 1
        contents).  Sequence current values will not be restored, either.
d444 1
a444 1
        ownership.  This makes the dump more standards compatible, but
d657 1
a657 1
      to disable triggers on user tables before inserting the data then emits commands to
d666 1
a666 1
      selectively, for instance only those for a specific table.  If
@


1.81
log
@Rename pg_restore -m to -j, and add documentation about what good numbers
are.  per discussion on hackers
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.80 2009/02/26 16:02:37 petere Exp $ -->
d682 3
a684 1
   restored table so the optimizer has useful statistics.
@


1.81.2.1
log
@Document that autovacuum may run ANALYZE
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.81 2009/03/20 09:21:08 petere Exp $ -->
d682 1
a682 3
   restored table so the optimizer has useful statistics; see
   <xref linkend="vacuum-for-statistics"> and
   <xref linkend="autovacuum"> for more information.
@


1.81.2.2
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.81.2.1 2009/08/07 20:55:05 alvherre Exp $ -->
d49 1
a49 2
   If a database name is specified, <application>pg_restore</application>
   connects to that database and restores archive contents directly into
d52 1
a52 1
   to a file or standard output.  This script output is equivalent to
d172 4
a175 1
           The archive is a <command>tar</command> archive.
d186 4
a189 1
           <application>pg_dump</application>.
d264 2
a265 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d275 5
a279 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.80
log
@Add a -w/--no-password option that prevents all password prompts to all
programs that have a -W/--password option.

In passing, remove the ancient PSQL_ALWAYS_GET_PASSWORDS compile option.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.79 2009/02/07 14:31:30 momjian Exp $ -->
d219 40
a284 22
      <term><option>-m <replaceable class="parameter">number-of-threads</replaceable></option></term>
      <term><option>--multi-thread=<replaceable class="parameter">number-of-threads</replaceable></option></term>
      <listitem>
       <para>
        Run the most time-consuming parts of <application>pg_restore</>
        &mdash; those which load data, create indexes, or create
        constraints &mdash; using multiple concurrent connections to the
        database. This option can dramatically reduce the time to restore a
        large database to a server running on a multi-processor machine.
       </para>

       <para>
        This option is ignored when emitting a script rather than connecting
        directly to a database server.  Multiple threads cannot be used
        together with <option>--single-transaction</option>.  Also, the input
        must be a plain file (not, for example, a pipe), and at present only
        the custom archive format is supported.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
@


1.79
log
@Document disabling the statistics collector pg_dump activity, and give a
bit more visibility to the PGOPTIONS environment variable supported by
libpq.

Bryce Nesbitt
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.78 2009/02/02 20:07:36 adunstan Exp $ -->
d514 15
@


1.78
log
@Provide for parallel restoration from a custom format archive. Each data and
post-data step is run in a separate worker child (a thread on Windows, a child
process elsewhere) up to the concurrent number specified by the new pg_restore
command-line --multi-thread | -m switch.

Andrew Dunstan, with some editing by Tom Lane.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.77 2009/01/05 16:54:36 tgl Exp $ -->
d562 1
@


1.77
log
@Add a --role option to pg_dump, pg_dumpall, and pg_restore.  This allows
performing dumps and restores in accordance with a security policy that
forbids logging in directly as superuser, but instead specifies that you
should log into an admin account and then SET ROLE to the superuser.

In passing, clean up some ugly and mostly-broken code for quoting shell
arguments in pg_dumpall.

Benedek László, with some help from Tom Lane
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.76 2008/09/07 19:12:57 tgl Exp $ -->
d245 22
@


1.76
log
@Clarify description of pg_restore's handling of large objects.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.75 2008/04/13 03:49:21 tgl Exp $ -->
d138 1
a138 1
        the database. The default is to continue and to display a count of 
d264 1
a264 1
        <command>ALTER OWNER</> or 
d432 14
d497 1
a497 1
        password before connecting to a database.  
d513 1
a513 2
      <term><option>-1</option></term>
      <term><option>--single-transaction</option></term>
d516 9
a524 5
        Execute the restore as a single transaction (that is, wrap the
        emitted commands in <command>BEGIN</>/<command>COMMIT</>).  This
        ensures that either all the commands complete successfully, or no
        changes are applied. This option implies
        <option>--exit-on-error</>.
@


1.75
log
@Turn the -i/--ignore-version options of pg_dump and pg_dumpall into no-ops:
the server version check is now always enforced.  Relax the version check to
allow a server that is of pg_dump's own major version but a later minor
version; this is the only case that -i was at all safe to use in.

pg_restore already enforced only a very weak version check, so this is
really just a documentation change for it.

Per discussion.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.74 2008/03/26 16:34:47 tgl Exp $ -->
d591 5
a595 2
      <application>pg_restore</application> will not restore large objects for a single table. If
      an archive contains large objects, then all large objects will be restored.
@


1.74
log
@Fix bad spelling and worse grammar in recent doc commits.  Propagate
pg_dump --ignore-version comments into pg_dumpall and pg_restore pages.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.73 2008/03/20 17:36:57 tgl Exp $ -->
d203 1
a203 2
        Ignore version mismatch between
        <application>pg_restore</application> and the database server.
@


1.73
log
@Support a --no-tablespaces option in pg_dump/pg_dumpall/pg_restore, so that
dumps can be loaded into databases without the same tablespaces that the
source had.  The option acts by suppressing all "SET default_tablespace"
commands, and also CREATE TABLESPACE commands in pg_dumpall's case.

Gavin Roy, with documentation and minor fixes by me.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.72 2007/12/11 19:57:32 tgl Exp $ -->
d203 2
a204 1
        Ignore database version checks.
@


1.72
log
@Make documentation of -W options more accurate and uniform.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.71 2007/05/15 19:13:55 neilc Exp $ -->
d277 11
@


1.72.2.1
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.72 2007/12/11 19:57:32 tgl Exp $ -->
d49 1
a49 2
   If a database name is specified, <application>pg_restore</application>
   connects to that database and restores archive contents directly into
d52 1
a52 1
   to a file or standard output.  This script output is equivalent to
d172 4
a175 1
           The archive is a <command>tar</command> archive.
d186 4
a189 1
           <application>pg_dump</application>.
d224 2
a225 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d235 5
a239 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.71
log
@Various fixes for the SGML docs. Consistently use spaces before/after
parentheses in syntax descriptions. Consistently use the present tense
when describing the basic purpose of each "DROP" command. Add a few
more hyperlinks.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.70 2007/03/26 17:23:37 tgl Exp $ -->
d461 1
a461 1
        Connect as the given user.
d471 12
a482 2
        Force a password prompt.  This should happen automatically if
        the server requires password authentication.
@


1.70
log
@Fix seriously broken markup for libpq-envars cross-references.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.69 2007/02/20 18:10:58 momjian Exp $ -->
d14 2
a15 1
   restore a <productname>PostgreSQL</productname> database from an archive file created by pg_dump
@


1.69
log
@More clearly document that most PostgreSQL utilities support libpq
environment variables.  Backpatch to 8.2.X.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.68 2007/02/20 15:01:17 momjian Exp $ -->
d514 2
a515 2
   also uses the environment variables supported by <xref 
   linkend="libpq-envars" endterm="libpq">.
@


1.68
log
@Remove "History" sections for pg_dump and pg_restore.  I don't think
anyone cares because the last history change was for PostgreSQL 7.1.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.67 2007/02/01 04:39:33 neilc Exp $ -->
d511 7
d530 3
a532 1
   example, <xref linkend="app-psql">.
a691 1
   <member>Environment Variables (<xref linkend="libpq-envars">)</member>
@


1.67
log
@This patch adds documentation for the long-version parameters --username
and --password for pg_dump, pg_dumpall and pg_restore, per complaint by
Michael Schmidt. Patch from Magnus Hagander.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.66 2007/02/01 00:28:19 momjian Exp $ -->
a676 9
  <title>History</title>

  <para>
   The <application>pg_restore</application> utility first appeared in
   <productname>PostgreSQL</productname> 7.1.
  </para>
 </refsect1>

 <refsect1>
@


1.66
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.65 2007/01/31 23:26:04 momjian Exp $ -->
d457 1
d460 1
a460 1
        Connect as the given user
d467 1
@


1.65
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64 2006/11/26 18:11:11 tgl Exp $ -->
d626 1
a626 1
   The listing file consists of a header and one line for each item, e.g.,
d657 1
a657 1
   Lines in the file can be commented out, deleted, and reordered. For example,
@


1.64
log
@Make pg_restore usage examples more useful: illustrate restoring into
both the same database name and a different one.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.63 2006/10/14 23:07:22 tgl Exp $ -->
d236 1
a236 1
        order they appear in the file. Lines can be moved and may also
d392 1
a392 1
        depending on the history of the objects in the dump, may not restore
d405 2
a406 2
        This behavior is useful when the target database may already
        contain the desired table contents.  For example,
d408 1
a408 1
        such as <productname>PostGIS</> may already be loaded in
d552 1
a552 1
      middle, the system catalogs may be left in the wrong state.
@


1.64.2.1
log
@More clearly document that most PostgreSQL utilities support libpq
environment variables.  Backpatch to 8.2.X.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64 2006/11/26 18:11:11 tgl Exp $ -->
a508 7

  <para>
   This utility, like most other <productname>PostgreSQL</> utilities,
   also uses the environment variables supported by <xref 
   linkend="libpq-envars" endterm="libpq">.
  </para>

d521 1
a521 3
   example, <xref linkend="app-psql">.  Also, any default connection
   settings and environment variables used by the
   <application>libpq</application> front-end library will apply.
d690 1
@


1.64.2.2
log
@Fix seriously broken markup for libpq-envars cross-references.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64.2.1 2007/02/20 18:11:17 momjian Exp $ -->
d512 2
a513 2
   also uses the environment variables supported by <application>libpq</>
   (see <xref linkend="libpq-envars">).
@


1.64.2.3
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64.2.2 2007/03/26 17:23:45 tgl Exp $ -->
d48 1
a48 2
   If a database name is specified, <application>pg_restore</application>
   connects to that database and restores archive contents directly into
d51 1
a51 1
   to a file or standard output.  This script output is equivalent to
d171 4
a174 1
           The archive is a <command>tar</command> archive.
d185 4
a188 1
           <application>pg_dump</application>.
d223 2
a224 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d234 5
a238 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.63
log
@Code review for --no-data-for-failed-tables patch.  Instead of trashing
one of the program's core data structures, make use of the existing
ability to selectively exclude TOC items by ID.  Slightly more code but
much less likely to create future maintenance problems.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.62 2006/10/07 20:59:04 petere Exp $ -->
d583 2
a584 2
   To dump a database called <literal>mydb</> to a <filename>tar</filename>
   file:
d587 1
a587 1
<prompt>$</prompt> <userinput>pg_dump -Ft mydb &gt; db.tar</userinput>
d592 1
a592 2
   To reload this dump into an
   existing database called <literal>newdb</>:
d595 2
a596 1
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
d598 20
d624 1
a624 1
<prompt>$</prompt> <userinput>pg_restore -l archive.file &gt; archive.list</userinput>
d630 1
a630 1
;     dbname: birds
d668 1
a668 1
<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
@


1.62
log
@The -X option in pg_dump was supposed to be a workaround for the lack of
portable long options.  But we have had portable long options for a long
time now, so this is obsolete.  Now people have added options which *only*
work with -X but not as regular long option, so I'm putting a stop to this:
-X is deprecated; it still works, but it has been removed from the
documentation, and please don't add more of them.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.61 2006/09/16 00:30:19 momjian Exp $ -->
d399 1
a399 1
      <term><option>--no-data-for-failed-tables</></term>
d402 14
a415 6
       By default, table data objects are restored even if the
       associated table could not be successfully created (e. g.
       because it already exists). With this option, such table
       data is silently ignored. This is useful for dumping and
       restoring databases with tables which contain auxiliary data
       for PostgreSQL extensions (e. g. PostGIS).
@


1.61
log
@Remove emacs info from footer of SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.60 2006/08/01 18:21:44 momjian Exp $ -->
a363 1
      <term><option>-X disable-triggers</></term>
a385 1
      <term><option>-X use-set-session-authorization</option></term>
d399 1
a399 1
      <term><option>-X no-data-for-failed-tables</></term>
@


1.60
log
@Add pg_dump -X no-data-for-failed-tables option to suppress loading data
if table creation failed (the table already exists).

Martin Pitt
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.59 2006/03/17 16:02:47 petere Exp $ -->
a667 17

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
@


1.59
log
@Document long names for format options (plain, tar, custom).  They already
worked and someone asked about them, so we might as well document them.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.58 2006/02/13 21:29:08 tgl Exp $ -->
a363 14
      <term><option>-X use-set-session-authorization</option></term>
      <term><option>--use-set-session-authorization</option></term>
      <listitem>
       <para>
        Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
        instead of <command>ALTER OWNER</> commands to determine object
        ownership.  This makes the dump more standards compatible, but
        depending on the history of the objects in the dump, may not restore
        properly.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d386 28
@


1.58
log
@Improve documentation of --single-transaction option: fix markup, and
don't promise more than the code actually delivers.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.57 2006/02/12 04:04:32 momjian Exp $ -->
d168 1
d181 1
@


1.57
log
@Add psql option:

	-1 or --single-transaction

Simon Riggs
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.56 2005/11/01 21:09:50 tgl Exp $ -->
d457 5
a461 3
        Force the restore to execute as a single transaction. Either all
        SQL statements complete successfully, or no changes are applied. This
        option also forces --exit-on-error.
@


1.56
log
@Make an editorial pass over the reference pages.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.55 2005/07/27 13:42:01 neilc Exp $ -->
d451 13
@


1.56.2.1
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.56 2005/11/01 21:09:50 tgl Exp $ -->
d48 1
a48 2
   If a database name is specified, <application>pg_restore</application>
   connects to that database and restores archive contents directly into
d51 1
a51 1
   to a file or standard output.  This script output is equivalent to
d170 4
a173 1
           The archive is a <command>tar</command> archive.
d183 4
a186 1
           <application>pg_dump</application>.
d221 2
a222 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d232 5
a236 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.55
log
@Add some missing SGML markup.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.54 2005/07/25 22:12:31 tgl Exp $ -->
d246 3
a248 3
        Restore only definitions and/or data in the named schema. Not to be
        confused with the <option>-s</option> option.  This can be combined with
        <option>-t</option> option.
d301 4
a304 2
        Restore only the schema (data definitions), not the data.
        Sequence values will be reset.
d366 5
a370 4
        Output SQL standard <command>SET SESSION AUTHORIZATION</>
        commands instead of <command>ALTER OWNER</> commands.  This
        makes the dump more standards compatible, but depending on the
        history of the objects in the dump, may not restore properly.
@


1.54
log
@Add SET ROLE.  This is a partial commit of Stephen Frost's recent patch;
I'm still working on the has_role function and information_schema changes.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.53 2005/06/21 20:45:43 tgl Exp $ -->
d364 4
a367 4
        Output SQL standard SET SESSION AUTHORIZATION commands instead of
        ALTER OWNER commands.  This makes the dump more standards compatible,
        but depending on the history of the objects in the dump, may not
        restore properly.
@


1.53
log
@pg_dump can now dump large objects even in plain-text output mode, by
using the recently added lo_create() function.  The restore logic in
pg_restore is greatly simplified as well, since there's no need anymore
to try to adjust database references to match a new set of blob OIDs.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.52 2005/06/09 17:56:51 momjian Exp $ -->
d364 2
a365 2
        Output SQL standard SET SESSION AUTHORIZATION commands instead
        of OWNER TO commands.  This makes the dump more standards compatible,
@


1.52
log
@Since I needed this feature badly, I added the -n / --schema switch to
pg_restore. It restores the given schemaname only. It can be used in
conjunction with the -t and other switches to make the selection very
fine grained.

Richard van den Bergg, CISSP
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.51 2005/05/29 03:32:18 momjian Exp $ -->
d47 7
a53 8
   <application>pg_restore</application> can operate in two modes: If
   a database name is specified, the archive is restored directly into
   the database.  (Large objects can only be restored by using such a direct
   database connection.)  Otherwise, a script containing the SQL
   commands necessary to rebuild the database is created (and written
   to a file or standard output), similar to the ones created by the
   <application>pg_dump</application> plain text format.  Some of the
   options controlling the script output are therefore analogous to
d543 2
a544 2
   To dump a database called <literal>mydb</> that contains
   large objects to a <filename>tar</filename> file:
d547 1
a547 1
<prompt>$</prompt> <userinput>pg_dump -Ft -b mydb &gt; db.tar</userinput>
d552 1
a552 1
   To reload this database (with large objects) to an
@


1.51
log
@Add reference to libpq environment variables for client applications.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.50 2005/01/23 00:30:31 momjian Exp $ -->
d243 12
@


1.50
log
@Add tools/find_gt_lt to find < and > in SGML source.

Lowercase some uppercase tags so tools is more reliable at finding
problems.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49 2005/01/04 03:58:16 tgl Exp $ -->
d619 1
@


1.49
log
@More minor updates and copy-editing.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.48 2004/08/20 04:20:22 momjian Exp $ -->
d233 2
a234 2
        Restore elements in <REPLACEABLE
        CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
@


1.49.4.1
log
@Add tools/find_gt_lt to find < and > in SGML source.

Lowercase some uppercase tags so tools is more reliable at finding
problems.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49 2005/01/04 03:58:16 tgl Exp $ -->
d233 2
a234 2
        Restore elements in <replaceable class="PARAMETER">
        list-file</replaceable> only, and in the
@


1.49.4.2
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49.4.1 2005/01/23 00:37:56 momjian Exp $ -->
d171 4
a174 1
           The archive is a <command>tar</command> archive.
d184 4
a187 1
           <application>pg_dump</application>.
d222 2
a223 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d233 5
a237 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.48
log
@> Please find attached a submission to add a "exit on error" option to
> pg_restore, as it seems that some people have scripts that rely on the
> previous "abort on error" default behavior when restoring data with a
> direct connection.
>
> Fabien Coelho
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.47 2004/07/13 02:59:49 momjian Exp $ -->
d91 1
a91 1
	Restore only the data, not the schema (data definitions).
d101 1
a101 1
	Clean (drop) database objects before recreating them.
d161 4
a164 4
	Specify format of the archive.  It is not necessary to specify
	the format, since <application>pg_restore</application> will
	determine the format automatically. If specified, it can be
	one of the following:
d201 1
a201 1
	Ignore database version checks.
d211 1
a211 1
	Restore definition of named index only.
d248 10
a257 9
	ownership of objects to match the original database.
	By default, <application>pg_restore</application> issues
	<command>SET SESSION AUTHORIZATION</command>
	statements to set ownership of created schema elements.
	These statements will fail unless the initial connection to the
	database is made by a superuser
	(or the same user that owns all of the objects in the script).
	With <option>-O</option>, any user name can be used for the
	initial connection, and this user will own all the created objects.
d268 2
a269 2
	name and arguments exactly as they appear in the dump file's table
	of contents.
d280 1
a280 1
	compatibility.
d302 1
a302 1
	This is only relevant if <option>--disable-triggers</> is used.
d332 1
a332 1
	Specifies verbose mode.
d343 1
a343 1
	Prevent restoration of access privileges (grant/revoke commands).
d353 4
a356 4
	Output SQL standard SET SESSION AUTHORIZATION commands instead
	of OWNER TO commands.  This makes the dump more standards compatible,
	but depending on the history of the objects in the dump, may not
	restore properly.
d367 5
a371 5
	It instructs <application>pg_restore</application> to execute commands
	to temporarily disable triggers on the target tables while
	the data is reloaded.  Use this if you have referential
	integrity checks or other triggers on the tables that you
	do not want to invoke during data reload.
d376 4
a379 4
	<option>--disable-triggers</> must be done as superuser.  So, you
	should also specify a superuser name with <option>-S</>, or
	preferably run <application>pg_restore</application> as a
	<productname>PostgreSQL</> superuser.
d397 5
a401 5
	Specifies the host name of the machine on which the server is
	running.  If the value begins with a slash, it is used as the
	directory for the Unix domain socket. The default is taken
	from the <envar>PGHOST</envar> environment variable, if set,
	else a Unix domain socket connection is attempted.
d411 4
a414 4
	Specifies the TCP port or local Unix domain socket file
	extension on which the server is listening for connections.
	Defaults to the <envar>PGPORT</envar> environment variable, if
	set, or a compiled-in default.
@


1.47
log
@Change pg_dump to use ALTER OWNER commands instead of SET SESSION
AUTHORIZATION commands by default.  Move all GRANT and REVOKE commands
to the end of the dump to avoid restore failures in several situations.
Bring back --use-set-session-authorization option to get previous SET
behaviour

Christopher Kings-Lyne
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.46 2004/02/17 09:07:16 neilc Exp $ -->
d133 12
@


1.46
log
@Add a few more <xref> tags to the SGML docs, where appropriate. Original
patch from Michael Glaesemann, additional changes by Neil Conway.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.45 2003/12/06 03:00:10 tgl Exp $ -->
d340 4
a343 4
        This option is obsolete but still accepted for backwards
	compatibility.
        <application>pg_restore</application> now always behaves in the
	way formerly selected by this option.
@


1.45
log
@Massive overhaul of pg_dump: make use of dependency information from
pg_depend to determine a safe dump order.  Defaults and check constraints
can be emitted either as part of a table or domain definition, or
separately if that's needed to break a dependency loop.  Lots of old
half-baked code for controlling dump order removed.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.44 2003/11/29 19:51:39 pgsql Exp $ -->
d113 1
a113 1
        used only to issue the initial <literal>CREATE DATABASE</>
d457 1
a457 1
   example, <application>psql</application>.
@


1.44
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d1 1
a1 1
<!-- $PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.43 2003/09/23 22:48:53 tgl Exp $ -->
a230 29
      <term><option>-N</option></term>
      <term><option>--orig-order</option></term>
      <listitem>
       <para>
        Restore items in the order they were originally generated within
        <application>pg_dump</application>.  This option has no known
	practical use, since <application>pg_dump</application> generates
	the items in an order convenient to it, which is unlikely to be a
	safe order for restoring them.  (This is <emphasis>not</> the order
	in which the items are ultimately listed in the archive's table of
	contents.)  See also <option>-r</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o</option></term>
      <term><option>--oid-order</option></term>
      <listitem>
       <para>
        Restore items in order by OID.  This option is of limited usefulness,
	since OID is only an approximate indication of original creation
	order.  This option overrides <option>-N</> if both are specified.
	See also <option>-r</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
a256 25
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-r</option></term>
      <term><option>--rearrange</option></term>
      <listitem>
       <para>
        Rearrange items by object type (this occurs after the sorting
	specified by <option>-N</option> or <option>-o</option>, if
	given).  The rearrangement is intended to give the best possible
	restore performance.
       </para>

       <para>
        When none of <option>-N</option>, <option>-o</option>, and
	<option>-r</> appear, <application>pg_restore</application> restores
	items in the order they appear in the dump's table of contents,
	or in the order they appear in the  <REPLACEABLE
        CLASS="PARAMETER">list-file</REPLACEABLE> if <option>-L</> is
	given.  The combination of <option>-o</> and <option>-r</>
	duplicates the sorting done by <application>pg_dump</application>
	before creating the dump's table of contents,
	and so it is normally unnecessary to specify it.
@


1.43
log
@pg_dump/pg_restore now always use SET SESSION AUTHORIZATION, not \connect,
to control object ownership.  The use-set-session-authorization and
no-reconnect switches are obsolete (still accepted on the command line,
but they don't do anything).  This is a precursor to fixing handling
of CREATE SCHEMA, which will be a separate commit.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.42 2003/09/11 21:42:20 momjian Exp $ -->
@


1.43.2.1
log
@Improve documentation of pg_restore's -l and -L switches to point out their
interactions with filtering switches, such as -n and -t.  Per a complaint
from Russell Smith.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.43 2003/09/23 22:48:53 tgl Exp $ -->
d159 4
a162 1
           The archive is a <command>tar</command> archive.
d172 4
a175 1
           <application>pg_dump</application>.
d210 2
a211 3
        can be used as input to the <option>-L</option> option.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-l</>, they will restrict the items listed.
d221 5
a225 12
        Restore only those archive elements that are listed in <replaceable
        class="PARAMETER">list-file</replaceable>, and restore them in the
        order they appear in the file.  Note that
        if filtering switches such as <option>-n</> or <option>-t</> are
        used with <option>-L</>, they will further restrict the items restored.
       </para>
       <para>
        <replaceable class="PARAMETER">list-file</> is normally created by
        editing the output of a previous <option>-l</> operation.
        Lines can be moved or removed, and can also
        be commented out by placing a semicolon (<literal>;</literal>) at the
        start of the line.  See below for examples.
@


1.42
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.41 2003/08/31 17:32:24 petere Exp $ -->
d264 10
a273 4
        Prevent any attempt to restore original object
        ownership. Objects will be owned by the user name used to
        attach to the database. See also under <option>-R</option> and
        <option>-X use-set-session-authorization</option>.
d320 2
a321 14
        While restoring an archive, <application>pg_restore</application>
        typically has to reconnect to the database several times with
        different user names to set the correct ownership of the
        created objects.  If this is undesirable (e.g., because manual
        interaction (passwords) would be necessary for each
        reconnection), this option prevents
        <application>pg_restore</application> from issuing any reconnection
        requests.  (A connection request while in plain text mode, not
        connected to a database, is made by putting out a <xref
        linkend="app-psql"> <command>\connect</command> command.)
        However, this option is a rather blunt instrument because it
        makes <application>pg_restore</application> lose all object ownership
        information, <emphasis>unless</emphasis> you use the
        <option>-X use-set-session-authorization</option> option.
d394 4
a397 10
        Normally, if restoring an archive requires altering the
        current database user (e.g., to set correct object
        ownerships), a new connection to the database must be opened,
        which might require manual interaction (e.g., passwords).  If
        you use the <option>-X use-set-session-authorization</option> option,
        then <application>pg_restore</application> will instead use the <xref
        linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> command.  This has
        the same effect, but it requires that the user restoring the
        archive is a database superuser.  This option effectively
        overrides the <option>-R</option> option.
d419 1
a419 2
	preferably specify <option>--use-set-session-authorization</> and
	run <application>pg_restore</application> as a
@


1.41
log
@Add/edit index entries.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.40 2003/08/28 20:44:02 tgl Exp $ -->
d662 1
a662 1
   PostgreSQL 7.1.
@


1.40
log
@Make documentation of pg_restore's -N, -o, -r switches bear some
slight resemblance to their actual behavior.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.39 2003/06/11 16:29:42 tgl Exp $ -->
d17 4
@


1.39
log
@pg_dump and pg_restore were stripping quotes and downcasing some but
not all SQL identifiers taken from command line arguments.  We decided
years ago that that was a bad idea: identifiers taken from the command
line should be treated as literally correct.  Remove the inconsistent
code that has crept in recently.  Also fix pg_dump so that the combination
of --schema and --table does what you'd expect, namely dump exactly one
table from exactly one schema.  Per gripe from Deepak Bhole of Red Hat.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.38 2003/03/25 16:15:43 petere Exp $ -->
d45 2
a46 2
   the database.  Large objects can only be restored by using a direct
   database connection.  Otherwise, a script containing the SQL
d231 7
a237 5
        Restore items in the original dump order. By default
        <application>pg_dump</application> will dump items in an order
        convenient to <application>pg_dump</application>, then save the
        archive in a modified OID order. This option overrides the OID
        ordering.
d247 4
a250 5
        Restore items in the OID order. By default
        <application>pg_dump</application> will dump items in an order
        convenient to <application>pg_dump</application>, then save the
        archive in a modified OID order. This option enforces strict
        OID ordering.
d285 16
a300 7
        Restore items in modified OID order. By default
        <application>pg_dump</application> will dump items in an order
        convenient to <application>pg_dump</application>, then save the
        archive in a modified OID order. Most objects will be restored
        in OID order, but some things (e.g., rules and indexes) will
        be restored at the end of the process irrespective of their
        OIDs. This option is the default.
@


1.39.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.41 2003/08/31 17:32:24 petere Exp $ -->
a17 4
 <indexterm zone="app-pgrestore">
  <primary>pg_restore</primary>
 </indexterm>

d45 2
a46 2
   the database.  (Large objects can only be restored by using such a direct
   database connection.)  Otherwise, a script containing the SQL
d231 5
a235 7
        Restore items in the order they were originally generated within
        <application>pg_dump</application>.  This option has no known
	practical use, since <application>pg_dump</application> generates
	the items in an order convenient to it, which is unlikely to be a
	safe order for restoring them.  (This is <emphasis>not</> the order
	in which the items are ultimately listed in the archive's table of
	contents.)  See also <option>-r</>.
d245 5
a249 4
        Restore items in order by OID.  This option is of limited usefulness,
	since OID is only an approximate indication of original creation
	order.  This option overrides <option>-N</> if both are specified.
	See also <option>-r</>.
d284 7
a290 16
        Rearrange items by object type (this occurs after the sorting
	specified by <option>-N</option> or <option>-o</option>, if
	given).  The rearrangement is intended to give the best possible
	restore performance.
       </para>

       <para>
        When none of <option>-N</option>, <option>-o</option>, and
	<option>-r</> appear, <application>pg_restore</application> restores
	items in the order they appear in the dump's table of contents,
	or in the order they appear in the  <REPLACEABLE
        CLASS="PARAMETER">list-file</REPLACEABLE> if <option>-L</> is
	given.  The combination of <option>-o</> and <option>-r</>
	duplicates the sorting done by <application>pg_dump</application>
	before creating the dump's table of contents,
	and so it is normally unnecessary to specify it.
@


1.38
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.37 2003/03/24 14:32:51 petere Exp $ -->
d272 3
a274 1
        Restore the named function only.
d323 1
a323 1
        Restore only the schema (data defintions), not the data.
d562 1
a562 1
   restored object so the optimizer has useful statistics.
@


1.37
log
@Another big editing pass for consistent content and presentation.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.36 2003/03/18 00:02:11 momjian Exp $ -->
a656 1
   <member>&cite-admin;</member>
@


1.36
log
@Add mention of ANALYZE after object restore.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.35 2003/01/19 00:13:31 momjian Exp $ -->
a3 4
 <docinfo>
  <date>2001-03-06</date>
 </docinfo>

d21 2
a22 1
   <arg rep="repeat"><replaceable>options</replaceable></arg>
d34 6
a39 12
   formats.  It
   will issue the commands necessary to re-generate all user-defined
   types, functions, tables, indexes, aggregates, and operators, as
   well as the data in the tables.
  </para>

  <para>
   The archive files contain information for
   <application>pg_restore</application> to rebuild the database, but also
   allow <application>pg_restore</application> to be selective about what is
   restored, or even to reorder the items prior to being restored. The
   archive files are designed to be portable across architectures.
d43 8
a50 7
   <application>pg_restore</application> can operate in two modes:  If a
   database name is specified, the archive is restored directly into
   the database.  Otherwise, a script containing the SQL commands
   necessary to rebuild the database is created (and written to a file
   or standard output), similar to the ones created by the
   <application>pg_dump</application> plain text format.  Some of the options
   controlling the script output are therefore analogous to
d56 1
a56 1
   that is not present in the archive file; for instance, if the
d58 1
a58 1
   <command>INSERT</command>s</quote> option,
d68 1
a68 1
    <command>pg_restore</command> accepts the following command
d73 1
a73 1
      <term><replaceable class="parameter">archive-name</replaceable></term>
d87 1
a87 1
	Restore only the data, no schema (definitions).
d108 1
a108 1
        switch appears, the database named with <option>-d</option> is
d123 1
a123 2
        into the database. Large objects can only be restored by using
        a direct database connection.
a148 1
       </para>
d152 1
a152 1
         <term>t</term>
d155 1
a155 1
           Archive is a <filename>tar</filename> archive. Using this
d164 1
a164 1
         <term>c</term>
d167 1
a167 1
           Archive is in the custom format of
d176 1
d195 1
a195 2
	Restore definition for named <replaceable
	class="parameter">index</replaceable> only.
d205 1
a205 1
        List the contents of the archive. The output of this command
d221 1
a221 1
        start of the line.
d261 2
a262 1
        attach to the database.
d272 1
a272 1
        Specify a procedure or function to be restored.
d321 2
a322 1
	Restore the schema (definitions), no data. Sequence values will be reset.
d343 1
a343 1
	Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.
d353 1
a353 1
	  Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.
d426 1
a426 1
    <command>pg_restore</command> also accepts
d436 4
a439 2
	running.  If host begins with a slash, it is used as the
	directory for the Unix domain socket.
d449 5
a453 5
	Specifies the Internet TCP/IP port or local Unix domain socket
	file extension on which the server is listening for
	connections.  The port number defaults to 5432, or the value
	of the <envar>PGPORT</envar> environment variable (if set).
       </para>
d491 1
a491 1
      Default connection parameters.
d502 8
a509 39
  <msgset>
   <msgentry>
    <msg>
     <msgmain>
      <msgtext>
<screen>
Connection to database 'template1' failed.
connectDBStart() -- connect() failed: No such file or directory
        Is the postmaster running locally
        and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
</screen>
      </msgtext>
     </msgmain>
    </msg>

    <msgexplan>
       <para>
	<application>pg_restore</application> could not attach to the
        <productname>PostgreSQL</> server process on the specified
        host and port.  If you see this message, ensure that the
        server is running on the proper host and that you have
        specified the proper port.  If your site uses an
        authentication system, ensure that you have obtained the
        required authentication credentials.
       </para>
    </msgexplan>
   </msgentry>
  </msgset>  

   <note>
    <para>
     When a direct database connection is specified using the -d
     option, <application>pg_restore</application> internally executes
     <acronym>SQL</acronym> statements. If you have problems running
     <application>pg_restore</application>, make sure you are able to select
     information from the database using, for example,
     <application>psql</application>.
    </para>
   </note>
d522 1
a522 1
   additions, copy from template0 not template1, for example:
d524 1
a524 1
CREATE DATABASE foo WITH TEMPLATE = template0;
d534 4
a537 2
      When restoring data to a pre-existing table, <application>pg_restore</application> emits queries
      to disable triggers on user tables before inserting the data then emits queries to
a569 14
   To dump a database:
<screen>
<prompt>$</prompt> <userinput>pg_dump mydb &gt; db.out</userinput>
</screen>
  </para>

  <para>
   To reload this database:
<screen>
<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
</screen>
  </para>

  <para>
d619 1
a619 1
   Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
d632 2
a633 2
   could be used as input to <command>pg_restore</command> and would only restore
   items 10 and 6, in that order.
@


1.35
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.34 2003/01/06 18:53:24 petere Exp $ -->
d592 6
@


1.34
log
@Use our own version of getopt_long() if the OS doesn't have one.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.33 2002/11/21 23:34:43 petere Exp $ -->
d700 1
a700 1
   <member><citetitle>PostgreSQL Administrator's Guide</citetitle></member>
@


1.33
log
@Fixups for man pages
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.32 2002/11/15 03:11:18 momjian Exp $ -->
d77 1
a77 1
    line arguments.  (Long option forms are only available on some platforms.)
@


1.32
log
@SGML improvements.

Neil Conway
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.31 2002/10/11 23:03:48 petere Exp $ -->
d398 1
a398 1
        linkend="sql-set-session-authorization"> command.  This has
@


1.31
log
@Assorted reference page updates
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.30 2002/08/10 16:57:31 petere Exp $ -->
d420 6
a425 5
        Presently, the commands emitted for <option>--disable-triggers</>
	must be done as superuser.  So, you should also specify
	a superuser name with <option>-S</>, or preferably specify
	<option>--use-set-session-authorization</> and run
	<application>pg_restore</application> as a PostgreSQL superuser.
d526 6
a531 6
        PostgreSQL server
	process on the specified host and port.  If you see this message,
	ensure that the server
	is running on the proper host and that you have specified the proper
	port.  If your site uses an authentication system, ensure that you
	have obtained the required authentication credentials.
d541 1
a541 1
     SQL statements. If you have problems running
@


1.31.2.1
log
@Fixups for man pages
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.31 2002/10/11 23:03:48 petere Exp $ -->
d398 1
a398 1
        linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> command.  This has
@


1.30
log
@Make sure all clients have the same understanding of default user name
and database.  In particular, make script wrappers understand the
PGDATABASE environment variable.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_restore.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ -->
d25 1
a25 26
   <arg> -a </arg>
   <arg> -c </arg>
   <arg> -C </arg>
   <arg> -d <replaceable class="parameter">dbname</replaceable> </arg>
   <arg> -f <replaceable class="parameter">output-file</replaceable> </arg>
   <arg> -F <replaceable class="parameter">format</replaceable> </arg>
   <arg> -i </arg>
   <arg> -I <replaceable class="parameter">index</replaceable> </arg>
   <arg> -l </arg>
   <arg> -L <replaceable class="parameter">contents-file</replaceable> </arg>
   <group> <arg> -N </arg> <arg> -o </arg> <arg> -r </arg> </group>
   <arg> -O </arg>
   <arg> -P <replaceable class="parameter">function-name(argtype [, ...])</replaceable> </arg>
   <arg> -R </arg>
   <arg> -s </arg>
   <arg> -S </arg>
   <arg> -t  <replaceable class="parameter">table</replaceable> </arg>
   <arg> -T  <replaceable class="parameter">trigger</replaceable> </arg>
   <arg> -v </arg>
   <arg> -x </arg>
   <arg> -X <replaceable>keyword</replaceable></arg>
   <arg> -h  <replaceable class="parameter">host</replaceable> </arg>
   <arg> -p  <replaceable class="parameter">port</replaceable> </arg>
   <arg> -U <replaceable>username</replaceable> </arg>
   <arg> -W </arg>
   <arg> <replaceable class="parameter">archive-file</replaceable> </arg>
d31 1
a31 3
  <title>
   Description
  </title>
d34 1
a34 1
   <command>pg_restore</command> is a utility for restoring a
d45 2
a46 2
   <command>pg_restore</command> to rebuild the database, but also
   allow <command>pg_restore</command> to be selective about what is
d52 1
a52 1
   <command>pg_restore</command> can operate in two modes:  If a
d57 1
a57 1
   <command>pg_dump</command> plain text format.  Some of the options
d59 1
a59 1
   <command>pg_dump</command> options.
d63 1
a63 1
   Obviously, <command>pg_restore</command> cannot restore information
d67 1
a67 1
   <command>pg_restore</command> will not be able to load the data
d70 1
d72 2
a73 4
  <refsect2 id="app-pgrestore-options">
   <title>
    Options
   </title>
d115 5
a119 5
        Create the database before restoring into it.
	(When this switch appears, the database named with <option>-d</option>
	is used only 
	to issue the initial CREATE DATABASE command.  All data is restored
	into the database name that appears in the archive.)
d129 4
a132 2
        Connect to database <replaceable class="parameter">dbname</replaceable> and restore
        directly into the database. Large objects can only be restored by using a direct database connection.
d143 2
a144 1
	when used with <option>-l</option>. Default is the standard output.
d154 4
a157 3
	  Specify format of the archive.
        It is not necessary to specify the format, since <COMMAND>pg_restore</COMMAND> will
        determine the format automatically. If specified, it can be one of the following:
a160 1

d165 4
a168 3
           Archive is a <filename>tar</filename> archive. Using this archive format allows reordering and/or
           exclusion of schema elements at the time the database is restored. It is also possible to limit which
           data is reloaded at restore time.
d177 5
a181 3
           Archive is in the custom format of <command>pg_dump</command>. This is the most flexible format
           in that it allows reordering of data load as well as schema elements.
           This format is also compressed by default.
a184 1

a185 1

d204 2
a205 1
	Restore definition for named <replaceable class="parameter">index</replaceable> only.
d215 3
a217 2
        List the contents of the archive. The output of this command can be used with the <option>-L</option> option
        to restrict and reorder the items that are restored.
d227 4
a230 2
	  Restore elements in <REPLACEABLE CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
        order they appear in the file. Lines can be moved and may also be commented out by placing a <literal>;</literal> at the
d241 5
a245 2
        Restore items in the original dump order. By default <command>pg_dump</command> will dump items in an order convenient
        to <command>pg_dump</command>, then save the archive in a modified OID order. This option overrides the OID ordering.
d255 5
a259 2
        Restore items in the OID order. By default <command>pg_dump</command> will dump items in an order convenient
        to <command>pg_dump</command>, then save the archive in a modified OID order. This option enforces strict OID ordering.
d269 3
a271 2
        Prevent any attempt to restore original object ownership. Objects will be owned by the user name used
        to attach to the database.
d291 7
a297 4
        Restore items in modified OID order. By default <command>pg_dump</command> will dump items in an order convenient
        to <command>pg_dump</command>, then save the archive in a modified OID order. Most objects
        will be restored in OID order, but some things (e.g., rules and indexes) will be restored at the end of
        the process irrespective of their OIDs. This option is the default.
d307 1
a307 1
        While restoring an archive, <command>pg_restore</command>
d313 1
a313 1
        <command>pg_restore</command> from issuing any reconnection
d318 1
a318 1
        makes <command>pg_restore</command> lose all object ownership
d397 1
a397 1
        then <command>pg_restore</command> will instead use the <xref
d412 1
a412 1
	It instructs <command>pg_restore</command> to execute commands
d424 1
a424 1
	<command>pg_restore</command> as a superuser.
d442 3
a444 4
	Specifies the host name of the machine on which the
	server
	is running.  If host begins with a slash, it is used 
	as the directory for the Unix domain socket.
d454 4
a457 5
	Specifies the Internet TCP/IP port or local Unix domain socket file
	extension on which the server
	is listening for connections.  The port number defaults to 5432,
	or the value of the <envar>PGPORT</envar>
	environment variable (if set).
a481 2
  </refsect2>

d512 1
a512 1
<screen><computeroutput>
d517 1
a517 1
</computeroutput></screen>
d524 2
a525 2
	<command>pg_restore</command> could not attach to the
	<command>postmaster</command>
d538 6
a543 5
     When a direct database connection is specified using the -d option, <command>pg_restore</command>
     internally executes  <command>SQL</command> statements. If you  have problems running
     <command>pg_restore</command>,
     make sure you are able to select information from the database using, for
     example, <command>psql</command>.
d550 1
a550 3
  <title>
   Notes
  </title>
d553 6
a558 6
   If your installation has any local additions to the template1 database,
   be careful to load the output of <command>pg_restore</command> into a
   truly empty database; otherwise you are likely to get errors due to
   duplicate definitions of the added objects.  To make an empty database
   without any local additions, copy from template0 not template1,
   for example:
d565 1
a565 1
   The limitations of <command>pg_restore</command> are detailed below.
d570 1
a570 1
      When restoring data to a pre-existing table, <command>pg_restore</command> emits queries
d579 1
a579 1
      <command>pg_restore</command> will not restore large objects for a single table. If
d588 2
a589 2
   See the <xref linkend="app-pgdump"> documentation for details on
   limitations of <command>pg_dump</command>.
d595 1
a595 3
  <title>
   Examples
  </title>
d687 1
a687 1
   The <command>pg_restore</command> utility first appeared in
@


1.29
log
@Structure reference pages consistently.  Document that structure.
Add information about environment variables.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.28 2002/07/13 00:55:53 momjian Exp $ -->
d478 1
a478 1
        Connect as the given user.
@


1.28
log
@Re-add -I documentation, per Tom.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.27 2002/07/10 02:57:31 momjian Exp $ -->
d496 19
@


1.27
log
@Fix pg_restore flags in documentation.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.26 2002/07/04 03:04:54 momjian Exp $ -->
d32 1
a32 1
   <arg> -I  <replaceable class="parameter">index</replaceable> </arg>
d214 2
a215 2
      <term><option>-i </term>
      <term><option>--ignore-version</term>
d219 10
@


1.26
log
@Document function args are required for pg_restore -P.
Fix pg_dump to not quote the function name in the storage tag.
Fix pg_dump so GRANT/REVOKE(ACL) tag entries are not quoted, for
	consistency.
Fix pg_restore to properly handle quotes and some spaces in -P.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.25 2002/05/10 22:36:26 tgl Exp $ -->
d31 2
a32 1
   <arg> -i  <replaceable class="parameter">index</replaceable> </arg>
d214 2
a215 2
      <term><option>-i <replaceable class="parameter">index</replaceable></option></term>
      <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
d218 1
a218 1
	Restore definition for named <replaceable class="parameter">index</replaceable> only.
@


1.25
log
@First pass at schema-fying pg_dump/pg_restore.  Much to do still,
but the basic capability seems to work.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.24 2002/04/21 19:02:39 thomas Exp $ -->
d36 1
a36 1
   <arg> -P <replaceable class="parameter">function-name</replaceable> </arg>
d279 2
a280 2
      <term><option>-P <replaceable class="parameter">function-name</replaceable></option></term>
      <term><option>--function=<replaceable class="parameter">function-name</replaceable></option></term>
@


1.24
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.23 2002/03/22 19:20:42 petere Exp $ -->
d339 2
a340 2
        Specify the superuser user name to use when disabling triggers and/or setting ownership of schema elements.
        By default, <COMMAND>pg_restore</COMMAND> will use the current user name if it is a superuser.
d401 23
@


1.23
log
@Spell checking and markup additions
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.22 2002/02/11 00:14:10 tgl Exp $ -->
d9 1
a9 3
  <refentrytitle>
   pg_restore
  </refentrytitle>
@


1.22
log
@pg_dump and pg_restore man pages need to mention that one should restore
into a virgin database, ie, one created from template0, if there are any
site-local additions in template1.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.21 2001/11/28 20:49:10 petere Exp $ -->
d120 2
a121 2
      <term>-a</term>
      <term>--data-only</term>
d130 2
a131 2
      <term>-c</term>
      <term>--clean</term>
d140 2
a141 2
      <term>-C</term>
      <term>--create</term>
d154 2
a155 2
      <term>-d <replaceable class="parameter">dbname</replaceable></term>
      <term>--dbname=<replaceable class="parameter">dbname</replaceable></term>
d165 2
a166 2
      <term>-f <replaceable>filename</replaceable></term>
      <term>--file=<replaceable>filename</replaceable></term>
d176 2
a177 2
      <term>-F <replaceable class="parameter">format</replaceable></term>
      <term>--format=<replaceable class="parameter">format</replaceable></term>
d215 2
a216 2
      <term>-i <replaceable class="parameter">index</replaceable></term>
      <term>--index=<replaceable class="parameter">index</replaceable></term>
d225 2
a226 2
      <term>-l</term>
      <term>--list</term>
d236 2
a237 2
      <term>-L <replaceable class="parameter">list-file</replaceable></term>
      <term>--use-list=<replaceable class="parameter">list-file</replaceable></term>
d248 2
a249 2
      <term>-N</term>
      <term>--orig-order</term>
d259 2
a260 2
      <term>-o</term>
      <term>--oid-order</term>
d270 2
a271 2
      <term>-O</term>
      <term>--no-owner</term>
d281 2
a282 2
      <term>-P <replaceable class="parameter">function-name</replaceable></term>
      <term>--function=<replaceable class="parameter">function-name</replaceable></term>
d291 2
a292 2
      <term>-r</term>
      <term>--rearrange</term>
d304 2
a305 2
      <term>-R</term>
      <term>--no-reconnect</term>
d327 2
a328 2
      <term>-s</term>
      <term>--schema-only</term>
d337 2
a338 2
      <term>-S <replaceable class="parameter">username</replaceable></term>
      <term>--superuser=<replaceable class="parameter">username</replaceable></term>
d348 2
a349 2
      <term>-t <replaceable class="parameter">table</replaceable></term>
      <term>--table=<replaceable class="parameter">table</replaceable></term>
d358 2
a359 2
      <term>-T <replaceable class="parameter">trigger</replaceable></term>
      <term>--trigger=<replaceable class="parameter">trigger</replaceable></term>
d368 2
a369 2
      <term>-v</term>
      <term>--verbose</term>
d378 3
a380 3
      <term>-x</term>
      <term>--no-privileges</term>
      <term>--no-acl</term>
d389 2
a390 2
      <term>-X use-set-session-authorization</term>
      <term>--use-set-session-authorization</term>
d416 2
a417 2
      <term>-h <replaceable class="parameter">host</replaceable></term>
      <term>--host=<replaceable class="parameter">host</replaceable></term>
d429 2
a430 2
      <term>-p <replaceable class="parameter">port</replaceable></term>
      <term>--port=<replaceable class="parameter">port</replaceable></term>
d443 1
a443 1
      <term>-U <replaceable>username</replaceable></term>
d452 1
a452 1
      <term>-W</term>
@


1.21
log
@proof-reading
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.20 2001/11/26 23:09:21 tgl Exp $ -->
d517 12
d534 1
a534 1
      When restoring data to a table, <command>pg_restore</command> emits queries
d553 1
a553 1
   limitation of <command>pg_dump</command>.
@


1.20
log
@Fix confusion about -f switch: it's output not input.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.19 2001/11/19 03:58:25 tgl Exp $ -->
d63 1
a63 1
   <productname>Postgres</productname> database from an archive
d397 1
a397 1
        you use the <option>-X use-set-session-authorization</option>,
d421 1
a421 1
	<command>postmaster</command>
d434 1
a434 1
	extension on which the <command>postmaster</command>
d490 1
a490 1
	ensure that the <command>postmaster</command>
@


1.19
log
@A bunch of small doco updates motivated by scanning the comments on
the interactive docs.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.18 2001/10/23 22:11:22 tgl Exp $ -->
d31 1
a31 1
   <arg> -f <replaceable class="parameter">archive-file</replaceable> </arg>
d114 1
a114 1
       If not specified, and no <option>-f</option> option is specified, then the standard input is used.
@


1.18
log
@Editorial work on descriptions of options.
@
text
@d1 1
a1 1
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.17 2001/09/21 21:58:30 petere Exp $ -->
d587 1
a587 1
<prompt>$</prompt> <userinput>pg_restore archive.file -l &gt; archive.list</userinput>
d631 1
a631 1
<prompt>$</prompt> <userinput>pg_restore archive.file -L archive.list</userinput>
@


1.17
log
@For consistency with the rest of PostgreSQL, rename BLOBs to large objects
in messages and documentation.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.16 2001/09/13 15:55:24 petere Exp $ -->
d65 4
a68 1
   formats.
d76 1
a76 4
   archive files are designed to be portable across architectures.  It
   will issue the commands necessary to re-generate all user-defined
   types, functions, tables, indexes, aggregates, and operators, as
   well as the data in the tables.
d87 1
a87 1
   <command>pg_dump</command>.
a98 61
  <para>
   The most flexible output file format is the <quote>custom</quote>
   format (<option>-Fc</option>). It allows for selection and
   reordering of all archived items, and is compressed by default. The
   <filename>tar</filename> format (<option>-Ft</option>) is not
   compressed and it is not possible to reorder data when loading, but
   it is otherwise quite flexible.
  </para>

  <para>
   To reorder the items, it is first necessary to dump the table of
   contents of the archive:
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -l &gt; archive.list</userinput>
</screen>
   This file consists of a header and one line for each item, e.g.,
<programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: birds
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
;     Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
   Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
   internal archive ID assigned to each item.
  </para>

  <para>
   Lines in the file can be commented out, deleted, and reordered. For example,
<programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
   could be used as input to <command>pg_restore</command> and would only restore
   items 10 and 6, in that order.
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -L archive.list</userinput>
</screen>
  </para>

d134 1
a134 1
	Clean (drop) schema prior to create.
d144 5
a148 1
	Include SQL to create the schema.
d169 2
a170 2
        Specify output file for generated script. (Use with the
        <option>-l</option> option.) Default is the standard output.
d311 1
a311 1
        created objects.  If this is undesriable (e.g., because manual
d395 1
a395 1
        ownerships), a new connection to the database must be openend,
d580 52
@


1.16
log
@Replace ASCII-quotes with proper markup.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.15 2001/09/03 12:57:50 petere Exp $ -->
d216 1
a216 1
        directly into the database. BLOBs can only be restored by using a direct database connection.
d588 2
a589 2
      <command>pg_restore</command> will not restore BLOBs for a single table. If
      an archive contains BLOBs, then all BLOBs will be restored.
d623 2
a624 2
   To dump a database called mydb that contains
   <acronym>BLOB</acronym>s to a <filename>tar</filename> file:
d632 2
a633 2
   To reload this database (with <acronym>BLOB</acronym>s) to an
   existing database called newdb:
@


1.15
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.14 2001/08/22 20:23:23 petere Exp $ -->
d298 1
a298 1
        order they appear in the file. Lines can be moved and may also be commented out by placing a ';' at the
@


1.14
log
@Add option to output SET SESSION AUTHORIZATION commands rather than
\connect, to avoid possible password prompts and such, at the drawback of
having to have superuser access.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.13 2001/08/12 19:02:39 petere Exp $ -->
d20 1
a20 2
   Restore a <PRODUCTNAME>Postgres</PRODUCTNAME> database from an archive file created by
<command>pg_dump</command>
@


1.13
log
@Make pg_dump handle the new privileges.
Don't hardcode the maximum accepted server version, use PG_VERSION instead.
Install a notice processor so notices are handled like error messages.
Word smithing.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.12 2001/05/17 21:50:18 petere Exp $ -->
d47 1
d64 3
a66 2
   <productname>Postgres</productname> database dumped by
   <xref linkend="app-pgdump"> in one of the non-plain-text formats.
d70 8
a77 8
   The archive files, new with the 7.1 release, contain enough information for
   <command>pg_restore</command> to rebuild the database, but also allow
   <command>pg_restore</command> to be selective about what is restored,
   or even to reorder the items prior to being restored. The archive files are designed
   to be portable across architectures. <command>pg_dump</command> will
   produce the queries necessary to re-generate all user-defined types, functions,
   tables, indexes, aggregates, and operators.  In addition, all the data is copied
   out (in text format for scripts) so that it can be readily copied in again.
d81 8
a88 5
   <command>pg_restore</command> reads the archive file and outputs the appropriate
   SQL in the required order based on the command parameters. Obviously, it can not restore
   information that is not present in the dump file; so if the dump is made using the
   <quote>dump data as <command>INSERT</command>s</quote> option, <command>pg_restore</command> will not be able to
   load the data using <command>COPY</command> statements.
d92 6
a97 4
   The most flexible output file format is the <quote>custom</quote> format (<option>-Fc</option>). It allows for
   selection and reordering of all archived items, and is compressed by default. The <filename>tar</filename>
   format (<option>-Ft</option>) is not compressed and it is not possible to reorder
   data when loading, but it is otherwise quite flexible.
d101 11
a111 1
   To reorder the items, it is first necessary to dump the contents of the archive:
d366 14
a379 2
	  Prohibit <COMMAND>pg_restore</COMMAND> from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING>
        statements or reconnecting to the database if directly connected.
d446 19
d643 8
@


1.12
log
@Change "indices" to "indexes", per OED.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.11 2001/05/17 21:12:48 petere Exp $ -->
d408 1
d412 1
a412 1
	Prevent restoration of ACLs (grant/revoke commands).
@


1.11
log
@Add -U and -W options to pg_dump and friends to support non-interactive
specification of username (like in psql).  pg_dumpall now works with
password authentication.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.10 2001/03/17 16:27:31 petere Exp $ -->
d74 1
a74 1
   tables, indices, aggregates, and operators.  In addition, all the data is copied
d338 1
a338 1
        will be restored in OID order, but some things (e.g., rules and indices) will be restored at the end of
@


1.10
log
@Tuning for docbook2man.
@
text
@d1 1
a1 1
<!-- $Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.9 2001/03/06 18:55:57 petere Exp $ -->
d49 2
a50 1
   <arg> -u </arg>
d452 1
a452 1
      <term>-u</term>
d455 11
a465 1
	Use password authentication. Prompts for user name and password.
@


1.9
log
@Some editing, enhance markup, move description section before options list.
@
text
@d1 1
a1 1
<!-- $Header$ -->
a34 1
   <sbr>
a46 1
   <sbr>
a49 1
   <sbr>
@


1.8
log
@- Reflect change of option -U to -L
@
text
@d1 2
d4 4
d9 2
a10 2
  <refentrytitle id="app-pgrestore-title">
   <application>pg_restore</application>
d15 1
d17 2
a18 3
  <refname>
   <application>pg_restore</application>
  </refname>
d21 1
a21 1
<APPLICATION>pg_dump</APPLICATION>
d24 1
d26 121
a146 23
  <refsynopsisdivinfo>
   <date>2000-10-11</date>
  </refsynopsisdivinfo>
  <synopsis>
pg_restore [ <replaceable class="parameter">archive-file</replaceable>  ]
    [ -h  <replaceable class="parameter">host</replaceable>  ]
    [ -p  <replaceable class="parameter">port</replaceable>  ]
    [ -t  <replaceable class="parameter">table</replaceable>  ]
    [ -a  ] [ -c  ] [-C] [-d <replaceable class="parameter">name</replaceable>]
    [ -f <replaceable class="parameter">archive-file</replaceable>]
    [ -F <replaceable class="parameter">format</replaceable>]
    [ -i  <replaceable class="parameter">index</replaceable>  ]
    [ -l ] [ -L <replaceable class="parameter">contents-file</replaceable> ]
    [ -N  ] [ -o  ] [ -O ]
    [ -P <replaceable class="parameter">function-name</replaceable> ] [ -r ] [ -R ]
    [ -s  ] [ -S ] { -T  <replaceable class="parameter">trigger</replaceable> ] [ -u  ]
    [ -v  ] [ -x ]
  </synopsis>

  <refsect2 id="R2-APP-PG-RESTORE-1">
   <refsect2info>
    <date>2000-10-11</date>
   </refsect2info>
d148 1
a148 1
    Inputs
d150 1
d152 2
a153 2
    <application>pg_restore</application> accepts the following command
    line arguments:
d161 1
a161 1
       If not specified, and no '-f' option is specified, then STDIN is used.
d168 1
d178 1
d188 1
d198 1
d208 2
a209 1
      <term>-f</term>
d212 2
a213 1
	  Specify output file for generated script. Default is STDOUT.
d220 1
d224 1
a224 1
        It is not necessary to specify the format, since <APPLICATION>pg_restore</APPLICATION> will
d234 1
a234 1
           archive is a TAR archive. Using this archive format allows reordering and/or
d245 1
a245 1
           archive is in the custom format from pg_dump. This is the most flexible format
d259 1
d269 1
d272 1
a272 1
        List the contents of the archive. The output of this command can be used with the '-U, --use-list' option
d280 1
d283 3
a285 3
	    Restore elements in <REPLACEABLE CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
        order they appear in the file. Lines can be moved and may also be commented out by placing 
        a ';' at the start of the line.
d292 1
d295 2
a296 2
        Restore items in the original dump order. By default pg_dump will dump items in an order convenient
        to pg_dump, then save the archive in a modified OID order. This option overrides the OID ordering.
d303 1
d306 2
a307 2
        Restore items in the OID order. By default pg_dump will dump items in an order convenient
        to pg_dump, then save the archive in a modified OID order. This option enforces strict OID ordering.
d314 1
d317 1
a317 1
        Prevent any attempt to restore original object ownership. Objects will be owned by the username used
d324 2
a325 1
      <term>-P <replaceable class="parameter">procedure-name</replaceable></term>
d335 1
d338 3
a340 3
        Restore items in modified OID order. By default pg_dump will dump items in an order convenient
        to pg_dump, then save the archive in a modified OID order. Most objects
        will be restored in OID order, but some things (eg. RULES & INDEXES) will be restored at the end of
d348 1
d351 1
a351 1
	  Prohibit <APPLICATION>pg_restore</APPLICATION> from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING>
d359 1
d369 1
d372 2
a373 2
        Specify the superuser username to use when disabling triggers and/or setting ownership of schema elements.
        By default, <APPLICATION>pg_restore</APPLICATION> will use the current username if it is a superuser.
d380 1
d390 1
a398 9
      <term>-u</term>
      <listitem>
       <para>
	Use password authentication. Prompts for username and password.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d400 1
d410 1
d420 1
d422 1
a422 1
    <application>pg_restore</application> also accepts
d428 1
d431 2
a432 2
	Specifies the hostname of the machine on which the
	<application>postmaster</application>
d434 1
a434 1
	as the directory for the unix domain socket.
d441 1
d445 1
a445 1
	extension on which the <application>postmaster</application>
d453 8
d465 5
a469 10
  <refsect2 id="R2-APP-PG-RESTORE-2">
   <refsect2info>
    <date>2000-10-11</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>pg_restore</application> will create a script file,
    write to <filename>stdout</filename>, or restore a database directly.
d471 6
a476 3
    <variablelist>
     <varlistentry>
      <term><computeroutput>
d481 6
a486 2
       </computeroutput></term>
      <listitem>
d488 2
a489 2
	<application>pg_restore</application> could not attach to the
	<application>postmaster</application>
d491 1
a491 1
	ensure that the <application>postmaster</application>
d496 3
a498 19
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
       </computeroutput></term>
      <listitem>
       <para>
	You do not have a valid entry in the relation <literal>pg_shadow</literal>
	and and will not be allowed to access <productname>Postgres</productname>.
	Contact your <productname>Postgres</productname> administrator.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
d502 1
a502 1
     When a direct database connection is specified using the -d option, <application>pg_restore</application>
d504 1
a504 1
     <application>pg_restore</application>,
d506 1
a506 1
     example, <application>psql</application>.
d509 1
a509 92
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-PG-RESTORE-1">
  <refsect1info>
   <date>2000-10-11</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <application>pg_restore</application> is a utility for restoring a
      <productname>Postgres</productname> database dumped by <application>pg_dump</application>
      from any one of the non-plain-text output formats.
  </para>

  <para>
   The archive files, new with this relase, contain enough information for
   <application>pg_restore</application> to rebuild the database, but also allow
   <application>pg_restore</application> to be selective about what is restored,
   or even to reorder the items prior to being restored. The archive files should
   also be portable across architectures. <application>pg_dump</application> will
   produce the queries necessary to re-generate all user-defined types, functions,
   tables, indices, aggregates, and operators.  In addition, all the data is copied
   out (in text format for scripts) so that it can be readily copied in again.
  </para>

  <para>
   <application>pg_restore</application> reads the archive file and outputs the appropriate
   SQL in the required order based on the command parameters. Obviously, it can not restore
   information that is not present in the dump file; so if the dump is made using the
   'dump data as inserts' option, <application>pg_restore</application> will not be able to
   load the data using <command>COPY</command> statements.
  </para>

  <para>
   The most flexible output file format is the new 'custom' format (-Fc). It allows for
   selection and reordering of all archived items, and is compressed by default. The TAR
   format (-Ft) is not compressed and it is not possible to reorder
   data when loading, but it is otherwise quite flexible.
  </para>

  <para>
   To reorder the items, it is first necessary to dump the contents of the archive:
   <programlisting>
    $ pg_restore archive.file --list > archive.lis
   </programlisting>
   This file consists of a header and one line for each item, eg.
   <programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: birds
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
;     Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>

   Where semi-colons are comment delimiters, and the numbers at the start of lines refer to the
   internal archive ID assigned to each item. Lines in the file can be commented out, deleted,
   and/or reordered. For example,
   <programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
   </programlisting>
  </para>
  <para>
   Could be used as input to <application>pg_restore</application> and would only restore
   items 10 and 6, in that order.
   <programlisting>
    $ pg_restore acrhive.file --use=archive.lis
   </programlisting>
  </para>
a510 1
 </refsect1>
d512 1
a512 4
 <refsect1 id="R1-APP-PG-RESTORE-2">
  <refsect1info>
   <date>2000-10-11</date>
  </refsect1info>
d516 1
d518 1
a518 5
   See the <application>pg_dump</application> section for details on limitation of
   <application>pg_dump</application>.
  </para>
  <para>
   The limitations of pg_restore are detailed below.
d523 1
a523 1
      When restoring data to a table, <application>pg_restore</application> emits queries
d532 1
a532 1
      <application>pg_restore</application> will not restore BLOBs for a single table. If
d539 5
d546 2
a547 4
 <refsect1 id="R1-APP-PG-RESTORE-3">
  <refsect1info>
   <date>2000-10-11</date>
  </refsect1info>
d549 1
a549 1
   Usage
d551 1
d553 4
a556 5
   To create a custom archive for a database of the same name as the user:

   <programlisting>
$ pg_dump -Fc > db.out
   </programlisting>
d561 3
a563 4

   <programlisting>
$ pg_restore db.out | psql -e database
   </programlisting>
d567 2
a568 1
   To dump a database called mydb that contains BLOBs to a TAR file:
d570 3
a572 3
   <programlisting>
$ pg_dump -Ft mydb --blobs > db.tar
   </programlisting>
d576 2
a577 1
   To reload this database (with BLOBs) to an existing db called newdb:
d579 3
a581 3
   <programlisting>
$ pg_restore db.tar --db=newdb
   </programlisting>
d584 5
d590 6
@


1.7
log
@I'm attaching those diffs for the Reference Guide in a tar file, as
not all of them attached properly in the post I made a few minutes
ago. Please disregard those earlier files. The diffs in the tar file
replace them.

Pierce Tyler
@
text
@d28 2
a29 2
    [-f <replaceable class="parameter">archive-file</replaceable>]
    [-F <replaceable class="parameter">format</replaceable>]
d31 2
a32 1
    [ -l ] [ -N  ] [ -o  ] [ -O ]
d35 1
a35 1
    [-U <replaceable class="parameter">contents-file</replaceable> ] [ -v  ] [ -x ]
d164 11
a276 11
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-U <replaceable class="parameter">list-file</replaceable></term>
      <listitem>
       <para>
	  Restore elements in <REPLACEABLE CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
        order they appear in the file. Lines can be moved and may also be commented out by placing a ';' at the
        start of the line.
@


1.6
log
@Refine some things to create better looking man pages.
@
text
@d431 1
a431 1
   data load, but it is otherwise quite flexible.
d437 1
a437 1
    $ pg_restore acrhive.file --list > archive.lis
@


1.5
log
@Repair residual sillinesses from UUNET virtual host/socket path patch.
I hope all the dust has settled out now ...
@
text
@d6 1
@


1.4
log
@Make socket option specify just the directory, not the full path.
@
text
@d348 3
a350 2
connectDB() failed: Is the postmaster running and accepting connections
            at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
@


1.3
log
@Add mention of hostname leading slash handling to all manual pages that use -h.
@
text
@d311 1
a311 1
	as the path to a unix domain socket.
@


1.2
log
@Fix up id tag parameters to omit illegal underscores.
Remove lots of extraneous trailing ^Ms from pg_restore.sgml.
@
text
@d310 2
a311 2
	is running.  Defaults to using a local Unix domain socket
	rather than an IP connection.
@


1.1
log
@First pass at docs for pg_restore
@
text
@d13 2
a14 2
   Restore a <PRODUCTNAME>Postgres</PRODUCTNAME> database from an archive file created by 
<APPLICATION>pg_dump</APPLICATION>
d21 13
a33 13
  <synopsis>
pg_restore [ <replaceable class="parameter">archive-file</replaceable>  ] 
    [ -h  <replaceable class="parameter">host</replaceable>  ] 
    [ -p  <replaceable class="parameter">port</replaceable>  ]     
    [ -t  <replaceable class="parameter">table</replaceable>  ]     
    [ -a  ] [ -c  ] [-C] [-d <name>] 
    [-f <replaceable class="parameter">archive-file</replaceable>] 
    [-F <replaceable class="parameter">format</replaceable>] 
    [ -i  <replaceable class="parameter">index</replaceable>  ] 
    [ -l ] [ -N  ] [ -o  ] [ -O ] 
    [ -P <replaceable class="parameter">function-name</replaceable> ] [ -r ] [ -R ] 
    [ -s  ] [ -S ] { -T  <replaceable class="parameter">trigger</replaceable> ] [ -u  ] 
    [-U <replaceable class="parameter">contents-file</replaceable> ] [ -v  ] [ -x ] 
d52 1
a52 1
       Specifies the location of the archive file to be restored.
d67 18
a84 18
     <varlistentry>
      <term>-c</term>
      <listitem>
       <para>
	Clean (drop) schema prior to create.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-C</term>
      <listitem>
       <para>
	Include SQL to create the schema.
       </para>
      </listitem>
     </varlistentry>

d89 68
a156 2
        Connect to database <replaceable class="parameter">dbname</replaceable> and restore 
        directly into the database. BLOBs can only be restored by using a direct database connection.
a160 66
     <varlistentry>
      <term>-f</term>
      <listitem>
       <para>
	  Specify output file for generated script. Default is STDOUT.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-F <replaceable class="parameter">format</replaceable></term>
      <listitem>
       <para>
	  Specify format of the archive.
        It is not necessary to specify the format, since <APPLICATION>pg_restore</APPLICATION> will 
        determine the format automatically. If specified, it can be one of the following:
       </para>

       <variablelist>

        <varlistentry>
         <term>t</term>
         <listitem>
          <para>
           archive is a TAR archive. Using this archive format allows reordering and/or 
           exclusion of schema elements at the time the database is restored. It is also possible to limit which 
           data is reloaded at restore time.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>c</term>
         <listitem>
          <para>
           archive is in the custom format from pg_dump. This is the most flexible format 
           in that it allows reordering of data load as well as schema elements. 
           This format is also compressed by default.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>

      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-i <replaceable class="parameter">index</replaceable></term>
      <listitem>
       <para>
	Restore definition for named <replaceable class="parameter">index</replaceable> only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-l</term>
      <listitem>
       <para>
        List the contents of the archive. The output of this command can be used with the '-U, --use-list' option
        to restrict and reorder the items that are restored.
       </para>
      </listitem>
     </varlistentry>

d164 2
a165 2
       <para>
        Restore items in the original dump order. By default pg_dump will dump items in an order convenient 
d175 2
a176 2
        Restore items in the OID order. By default pg_dump will dump items in an order convenient 
        to pg_dump, then save the archive in a modified OID order. This option enforces strict OID ordering.
d185 2
a186 2
        Prevent any attempt to restore original object ownership. Objects will be owned by the username used
        to attach to the database.
d190 69
a258 69

     <varlistentry>
      <term>-P <replaceable class="parameter">procedure-name</replaceable></term>
      <listitem>
       <para>
        Specify a procedure or function to be restored.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-r</term>
      <listitem>
       <para>
        Restore items in modified OID order. By default pg_dump will dump items in an order convenient 
        to pg_dump, then save the archive in a modified OID order. Most objects
        will be restored in OID order, but some things (eg. RULES & INDEXES) will be restored at the end of
        the process irrespective of their OIDs. This option is the default. 
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-R</term>
      <listitem>
       <para>
	  Prohibit <APPLICATION>pg_restore</APPLICATION> from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> 
        statements or reconnecting to the database if directly connected.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-s</term>
      <listitem>
       <para>
	Restore the schema (definitions), no data. Sequence values will be reset.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-S <replaceable class="parameter">username</replaceable></term>
      <listitem>
       <para>
        Specify the superuser username to use when disabling triggers and/or setting ownership of schema elements.
        By default, <APPLICATION>pg_restore</APPLICATION> will use the current username if it is a superuser.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-t <replaceable class="parameter">table</replaceable></term>
      <listitem>
       <para>
	Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-T <replaceable class="parameter">trigger</replaceable></term>
      <listitem>
       <para>
	  Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.
       </para>
      </listitem>
     </varlistentry>

d268 11
a278 11
     <varlistentry>
      <term>-U <replaceable class="parameter">list-file</replaceable></term>
      <listitem>
       <para>
	  Restore elements in <REPLACEABLE CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
        order they appear in the file. Lines can be moved and may also be commented out by placing a ';' at the 
        start of the line.
       </para>
      </listitem>
     </varlistentry>

d300 1
a300 1
    <application>pg_restore</application> also accepts 
d308 1
a308 1
	Specifies the hostname of the machine on which the 
d320 1
a320 1
	Specifies the Internet TCP/IP port or local Unix domain socket file 
d353 2
a354 2
	<application>pg_restore</application> could not attach to the 
	<application>postmaster</application> 
d356 1
a356 1
	ensure that the <application>postmaster</application> 
d372 1
a372 1
	and and will not be allowed to access <productname>Postgres</productname>. 
d383 2
a384 2
     When a direct database connection is specified using the -d option, <application>pg_restore</application> 
     internally executes  <command>SQL</command> statements. If you  have problems running 
d401 82
a482 82
   <application>pg_restore</application> is a utility for restoring a
      <productname>Postgres</productname> database dumped by <application>pg_dump</application>
      from any one of the non-plain-text output formats.
  </para>

  <para>
   The archive files, new with this relase, contain enough information for 
   <application>pg_restore</application> to rebuild the database, but also allow 
   <application>pg_restore</application> to be selective about what is restored, 
   or even to reorder the items prior to being restored. The archive files should 
   also be portable across architectures. <application>pg_dump</application> will 
   produce the queries necessary to re-generate all user-defined types, functions, 
   tables, indices, aggregates, and operators.  In addition, all the data is copied 
   out (in text format for scripts) so that it can be readily copied in again.
  </para>

  <para>
   <application>pg_restore</application> reads the archive file and outputs the appropriate 
   SQL in the required order based on the command parameters. Obviously, it can not restore 
   information that is not present in the dump file; so if the dump is made using the 
   'dump data as inserts' option, <application>pg_restore</application> will not be able to
   load the data using <command>COPY</command> statements.
  </para>

  <para>
   The most flexible output file format is the new 'custom' format (-Fc). It allows for 
   selection and reordering of all archived items, and is compressed by default. The TAR 
   format (-Ft) is not compressed and it is not possible to reorder
   data load, but it is otherwise quite flexible.
  </para>

  <para>
   To reorder the items, it is first necessary to dump the contents of the archive:
   <programlisting>
    $ pg_restore acrhive.file --list > archive.lis    
   </programlisting>
   This file consists of a header and one line for each item, eg.
   <programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: birds
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
;     Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>

   Where semi-colons are comment delimiters, and the numbers at the start of lines refer to the 
   internal archive ID assigned to each item. Lines in the file can be commented out, deleted, 
   and/or reordered. For example,
   <programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
   </programlisting>
  </para>
  <para>
   Could be used as input to <application>pg_restore</application> and would only restore 
   items 10 and 6, in that order.
   <programlisting>
    $ pg_restore acrhive.file --use=archive.lis    
   </programlisting>
  </para>

d493 3
a495 3
   See the <application>pg_dump</application> section for details on limitation of
   <application>pg_dump</application>.
  </para>
d502 3
a504 3
      When restoring data to a table, <application>pg_restore</application> emits queries 
      to disable triggers on user tables before inserting the data then emits queries to 
      re-enable them after the data has been inserted.  If the restore is stopped in the 
d511 2
a512 2
      <application>pg_restore</application> will not restore BLOBs for a single table. If 
      an archive contains BLOBs, then all BLOBs will be restored. 
d535 25
a559 25
  <para>
   To reload this database:

   <programlisting>
$ pg_restore db.out | psql -e database
   </programlisting>
  </para>

  <para>
   To dump a database called mydb that contains BLOBs to a TAR file:

   <programlisting>
$ pg_dump -Ft mydb --blobs > db.tar
   </programlisting>
  </para>

  <para>
   To reload this database (with BLOBs) to an existing db called newdb:

   <programlisting>
$ pg_restore db.tar --db=newdb
   </programlisting>
  </para>


@
