head	1.118;
access;
symbols
	REL9_0_0:1.117
	REL9_1_ALPHA1:1.118
	REL9_0_RC1:1.117
	REL9_0_BETA4:1.117
	REL9_0_STABLE:1.117.0.4
	REL9_0_BETA3:1.117
	REL9_0_BETA2:1.117
	REL7_4_29:1.65.2.3
	REL8_0_25:1.76.4.1
	REL8_1_21:1.81.2.4
	REL8_2_17:1.92.2.3
	REL8_3_11:1.98.2.2
	REL8_4_4:1.113.2.1
	REL9_0_BETA1:1.117
	REL9_0_ALPHA5_BRANCH:1.117.0.2
	REL9_0_ALPHA5:1.117
	REL7_4_28:1.65.2.3
	REL8_0_24:1.76.4.1
	REL8_1_20:1.81.2.4
	REL8_2_16:1.92.2.3
	REL8_3_10:1.98.2.2
	REL8_4_3:1.113.2.1
	REL9_0_ALPHA4:1.116
	REL9_0_ALPHA4_BRANCH:1.116.0.2
	REL8_5_ALPHA3:1.114
	REL8_5_ALPHA3_BRANCH:1.114.0.6
	REL7_4_27:1.65.2.3
	REL8_0_23:1.76.4.1
	REL8_1_19:1.81.2.4
	REL8_2_15:1.92.2.3
	REL8_3_9:1.98.2.2
	REL8_4_2:1.113.2.1
	REL8_5_ALPHA2:1.114
	REL8_5_ALPHA2_BRANCH:1.114.0.4
	REL7_4_26:1.65.2.3
	REL8_0_22:1.76.4.1
	REL8_1_18:1.81.2.4
	REL8_2_14:1.92.2.3
	REL8_3_8:1.98.2.2
	REL8_4_1:1.113.2.1
	REL8_5_ALPHA1:1.114
	REL8_5_ALPHA1_BRANCH:1.114.0.2
	REL8_4_STABLE:1.113.0.2
	REL8_4_0:1.113
	REL8_4_RC2:1.113
	REL8_4_RC1:1.113
	REL8_4_BETA2:1.113
	REL8_4_BETA1:1.113
	REL7_4_25:1.65.2.3
	REL8_0_21:1.76.4.1
	REL8_1_17:1.81.2.4
	REL8_2_13:1.92.2.3
	REL8_3_7:1.98.2.2
	REL7_4_24:1.65.2.3
	REL8_0_20:1.76.4.1
	REL8_1_16:1.81.2.4
	REL8_2_12:1.92.2.3
	REL8_3_6:1.98.2.2
	REL7_4_23:1.65.2.3
	REL8_0_19:1.76.4.1
	REL8_1_15:1.81.2.4
	REL8_2_11:1.92.2.3
	REL8_3_5:1.98.2.2
	REL7_4_22:1.65.2.3
	REL8_0_18:1.76.4.1
	REL8_1_14:1.81.2.4
	REL8_2_10:1.92.2.3
	REL8_3_4:1.98.2.2
	REL7_4_21:1.65.2.2
	REL8_0_17:1.76
	REL8_1_13:1.81.2.3
	REL8_2_9:1.92.2.2
	REL8_3_3:1.98
	REL7_4_20:1.65.2.2
	REL8_0_16:1.76
	REL8_1_12:1.81.2.3
	REL8_2_8:1.92.2.2
	REL8_3_2:1.98
	REL8_2_7:1.92.2.2
	REL8_3_1:1.98
	REL8_3_STABLE:1.98.0.2
	REL8_3_0:1.98
	REL8_3_RC2:1.98
	REL7_3_21:1.52
	REL7_4_19:1.65.2.2
	REL8_0_15:1.76
	REL8_1_11:1.81.2.3
	REL8_2_6:1.92.2.2
	REL8_3_RC1:1.98
	REL8_3_BETA4:1.97
	REL8_3_BETA3:1.97
	REL8_3_BETA2:1.97
	REL8_3_BETA1:1.97
	REL7_3_20:1.52
	REL7_4_18:1.65.2.2
	REL8_0_14:1.76
	REL8_1_10:1.81.2.3
	REL8_2_5:1.92.2.2
	REL7_3_19:1.52
	REL7_4_17:1.65.2.2
	REL8_0_13:1.76
	REL8_1_9:1.81.2.3
	REL8_2_4:1.92.2.2
	REL8_0_12:1.76
	REL8_1_8:1.81.2.3
	REL8_2_3:1.92
	REL7_3_18:1.52
	REL7_4_16:1.65.2.2
	REL8_0_11:1.76
	REL8_1_7:1.81.2.3
	REL8_2_2:1.92
	REL8_0_10:1.76
	REL8_1_6:1.81.2.3
	REL8_2_1:1.92
	REL7_4_15:1.65.2.2
	REL7_3_17:1.52
	REL8_2_STABLE:1.92.0.2
	REL8_2_0:1.92
	REL8_2_RC1:1.91
	REL8_2_BETA3:1.91
	REL8_2_BETA2:1.91
	REL8_1_5:1.81.2.3
	REL8_0_9:1.76
	REL7_4_14:1.65.2.2
	REL7_3_16:1.52
	REL8_2_BETA1:1.88
	REL7_3_15:1.52
	REL7_4_13:1.65.2.2
	REL8_0_8:1.76
	REL8_1_4:1.81.2.3
	REL7_3_14:1.52
	REL7_4_12:1.65.2.2
	REL8_0_7:1.76
	REL8_1_3:1.81
	REL7_3_13:1.52
	REL7_4_11:1.65.2.2
	REL8_0_6:1.76
	REL8_1_2:1.81
	REL7_3_12:1.52
	REL7_4_10:1.65.2.2
	REL8_0_5:1.76
	REL8_1_1:1.81
	REL8_1_STABLE:1.81.0.2
	REL8_1_0:1.81
	REL8_1_0RC1:1.80
	REL8_1_0BETA4:1.80
	REL8_1_0BETA3:1.80
	REL7_3_11:1.52
	REL7_4_9:1.65.2.2
	REL8_0_4:1.76
	REL8_1_0BETA2:1.80
	REL8_1_0BETA1:1.80
	REL7_2_8:1.42
	REL7_3_10:1.52
	REL7_4_8:1.65.2.2
	REL8_0_3:1.76
	REL8_0_2:1.76
	REL7_2_7:1.42
	REL7_3_9:1.52
	REL7_4_7:1.65.2.2
	REL8_0_1:1.76
	REL8_0_STABLE:1.76.0.4
	REL8_0_0:1.76.0.2
	REL8_0_0RC5:1.75
	REL8_0_0RC4:1.75
	REL8_0_0RC3:1.74
	REL8_0_0RC2:1.74
	REL8_0_0RC1:1.74
	REL8_0_0BETA5:1.74
	REL8_0_0BETA4:1.74
	REL7_4_6:1.65.2.2
	REL7_3_8:1.52
	REL7_2_6:1.42
	REL8_0_0BETA3:1.73
	REL8_0_0BETA2:1.73
	REL7_2_5:1.42
	REL7_4_5:1.65.2.1
	REL7_3_7:1.52
	REL7_4_4:1.65.2.1
	REL8_0_0BETA1:1.73
	REL7_4_3:1.65.2.1
	REL7_4_2:1.65.2.1
	REL7_3_6:1.52
	REL7_4_1:1.65.2.1
	REL7_3_5:1.52
	REL7_4:1.65.2.1
	REL7_4_RC2:1.65.2.1
	REL7_4_STABLE:1.65.0.2
	REL7_4_RC1:1.65
	REL7_4_BETA5:1.65
	REL7_4_BETA4:1.65
	REL7_4_BETA3:1.64
	REL7_4_BETA2:1.62
	WIN32_DEV:1.62.0.2
	REL7_4_BETA1:1.62
	REL7_3_4:1.52
	REL7_3_2:1.52
	REL7_2_4:1.42
	REL7_3_STABLE:1.52.0.2
	REL7_2_3:1.42
	REL7_2_STABLE:1.42.0.2
	REL7_2:1.41
	REL7_2_RC2:1.41
	REL7_2_RC1:1.41
	REL7_2_BETA5:1.41
	REL7_2_BETA4:1.41
	REL7_2_BETA3:1.39
	REL7_2_BETA2:1.38
	REL7_2_BETA1:1.38
	REL7_1_2:1.31
	REL7_1_STABLE:1.31.0.2
	REL7_1_BETA:1.26
	REL7_1_BETA3:1.27
	REL7_1_BETA2:1.27
	REL7_1:1.31
	REL7_0_PATCHES:1.17.0.2
	REL7_0:1.17
	REL6_5_PATCHES:1.11.0.2
	REL6_5:1.11
	REL6_4:1.5.0.2;
locks; strict;
comment	@# @;


1.118
date	2010.07.22.01.22.33;	author rhaas;	state Exp;
branches;
next	1.117;

1.117
date	2010.02.23.17.28.09;	author tgl;	state Exp;
branches;
next	1.116;

1.116
date	2010.02.19.14.36.45;	author momjian;	state Exp;
branches;
next	1.115;

1.115
date	2010.02.19.03.50.03;	author momjian;	state Exp;
branches;
next	1.114;

1.114
date	2009.08.07.20.54.31;	author alvherre;	state Exp;
branches;
next	1.113;

1.113
date	2009.03.22.16.44.26;	author tgl;	state Exp;
branches
	1.113.2.1;
next	1.112;

1.112
date	2009.03.04.11.57.00;	author petere;	state Exp;
branches;
next	1.111;

1.111
date	2009.02.26.16.02.37;	author petere;	state Exp;
branches;
next	1.110;

1.110
date	2009.02.17.15.41.50;	author momjian;	state Exp;
branches;
next	1.109;

1.109
date	2009.02.10.00.55.21;	author momjian;	state Exp;
branches;
next	1.108;

1.108
date	2009.02.07.15.25.51;	author momjian;	state Exp;
branches;
next	1.107;

1.107
date	2009.02.07.14.31.30;	author momjian;	state Exp;
branches;
next	1.106;

1.106
date	2009.01.05.16.54.36;	author tgl;	state Exp;
branches;
next	1.105;

1.105
date	2008.08.26.00.03.15;	author tgl;	state Exp;
branches;
next	1.104;

1.104
date	2008.08.21.22.25.44;	author momjian;	state Exp;
branches;
next	1.103;

1.103
date	2008.07.20.18.43.30;	author tgl;	state Exp;
branches;
next	1.102;

1.102
date	2008.04.13.03.49.21;	author tgl;	state Exp;
branches;
next	1.101;

1.101
date	2008.03.26.16.34.47;	author tgl;	state Exp;
branches;
next	1.100;

1.100
date	2008.03.26.14.32.22;	author momjian;	state Exp;
branches;
next	1.99;

1.99
date	2008.03.20.17.36.57;	author tgl;	state Exp;
branches;
next	1.98;

1.98
date	2007.12.11.19.57.32;	author tgl;	state Exp;
branches
	1.98.2.1;
next	1.97;

1.97
date	2007.03.26.17.23.36;	author tgl;	state Exp;
branches;
next	1.96;

1.96
date	2007.02.20.18.10.58;	author momjian;	state Exp;
branches;
next	1.95;

1.95
date	2007.02.20.15.01.17;	author momjian;	state Exp;
branches;
next	1.94;

1.94
date	2007.02.01.04.39.33;	author neilc;	state Exp;
branches;
next	1.93;

1.93
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.92;

1.92
date	2006.11.28.22.54.18;	author tgl;	state Exp;
branches
	1.92.2.1;
next	1.91;

1.91
date	2006.10.23.18.10.32;	author petere;	state Exp;
branches;
next	1.90;

1.90
date	2006.10.09.23.36.58;	author tgl;	state Exp;
branches;
next	1.89;

1.89
date	2006.10.07.20.59.04;	author petere;	state Exp;
branches;
next	1.88;

1.88
date	2006.09.16.00.30.19;	author momjian;	state Exp;
branches;
next	1.87;

1.87
date	2006.08.01.18.05.04;	author momjian;	state Exp;
branches;
next	1.86;

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

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

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

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

1.82
date	2006.03.17.16.02.47;	author petere;	state Exp;
branches;
next	1.81;

1.81
date	2005.11.01.21.09.50;	author tgl;	state Exp;
branches
	1.81.2.1;
next	1.80;

1.80
date	2005.07.25.22.12.31;	author tgl;	state Exp;
branches;
next	1.79;

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

1.78
date	2005.06.21.20.45.43;	author tgl;	state Exp;
branches;
next	1.77;

1.77
date	2005.05.29.03.32.18;	author momjian;	state Exp;
branches;
next	1.76;

1.76
date	2005.01.17.04.30.37;	author neilc;	state Exp;
branches
	1.76.4.1;
next	1.75;

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

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

1.73
date	2004.07.13.02.59.49;	author momjian;	state Exp;
branches;
next	1.72;

1.72
date	2004.07.10.15.51.28;	author momjian;	state Exp;
branches;
next	1.71;

1.71
date	2004.06.07.20.35.57;	author momjian;	state Exp;
branches;
next	1.70;

1.70
date	2004.05.31.13.37.52;	author momjian;	state Exp;
branches;
next	1.69;

1.69
date	2004.03.23.22.06.08;	author tgl;	state Exp;
branches;
next	1.68;

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

1.67
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.66;

1.66
date	2003.11.04.09.55.39;	author petere;	state Exp;
branches;
next	1.65;

1.65
date	2003.09.23.22.48.53;	author tgl;	state Exp;
branches
	1.65.2.1;
next	1.64;

1.64
date	2003.09.11.21.42.20;	author momjian;	state Exp;
branches;
next	1.63;

1.63
date	2003.08.31.17.32.23;	author petere;	state Exp;
branches;
next	1.62;

1.62
date	2003.06.11.16.29.42;	author tgl;	state Exp;
branches
	1.62.2.1;
next	1.61;

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

1.60
date	2003.03.25.16.15.42;	author petere;	state Exp;
branches;
next	1.59;

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

1.58
date	2003.03.18.17.05.01;	author momjian;	state Exp;
branches;
next	1.57;

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

1.56
date	2003.02.13.04.54.15;	author momjian;	state Exp;
branches;
next	1.55;

1.55
date	2003.01.19.00.13.30;	author momjian;	state Exp;
branches;
next	1.54;

1.54
date	2003.01.06.18.53.24;	author petere;	state Exp;
branches;
next	1.53;

1.53
date	2002.11.15.03.11.18;	author momjian;	state Exp;
branches;
next	1.52;

1.52
date	2002.10.11.23.03.48;	author petere;	state Exp;
branches;
next	1.51;

1.51
date	2002.09.07.16.14.33;	author petere;	state Exp;
branches;
next	1.50;

1.50
date	2002.09.06.21.58.36;	author petere;	state Exp;
branches;
next	1.49;

1.49
date	2002.08.27.18.57.26;	author petere;	state Exp;
branches;
next	1.48;

1.48
date	2002.08.18.09.36.25;	author petere;	state Exp;
branches;
next	1.47;

1.47
date	2002.08.10.16.57.31;	author petere;	state Exp;
branches;
next	1.46;

1.46
date	2002.07.28.15.22.20;	author petere;	state Exp;
branches;
next	1.45;

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

1.44
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.43;

1.43
date	2002.03.22.19.20.42;	author petere;	state Exp;
branches;
next	1.42;

1.42
date	2002.02.11.00.14.10;	author tgl;	state Exp;
branches;
next	1.41;

1.41
date	2001.12.08.03.24.37;	author thomas;	state Exp;
branches;
next	1.40;

1.40
date	2001.11.28.20.49.10;	author petere;	state Exp;
branches;
next	1.39;

1.39
date	2001.11.18.20.35.02;	author petere;	state Exp;
branches;
next	1.38;

1.38
date	2001.10.23.22.11.22;	author tgl;	state Exp;
branches;
next	1.37;

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

1.36
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.35;

1.35
date	2001.08.22.20.23.23;	author petere;	state Exp;
branches;
next	1.34;

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

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

1.32
date	2001.05.17.21.12.48;	author petere;	state Exp;
branches;
next	1.31;

1.31
date	2001.03.17.16.27.31;	author petere;	state Exp;
branches;
next	1.30;

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

1.29
date	2001.03.06.05.22.18;	author pjw;	state Exp;
branches;
next	1.28;

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

1.27
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2000.11.30.23.20.50;	author tgl;	state Exp;
branches;
next	1.25;

1.25
date	2000.11.22.01.41.13;	author momjian;	state Exp;
branches;
next	1.24;

1.24
date	2000.11.21.15.39.09;	author pjw;	state Exp;
branches;
next	1.23;

1.23
date	2000.11.13.23.57.20;	author momjian;	state Exp;
branches;
next	1.22;

1.22
date	2000.11.13.23.37.51;	author momjian;	state Exp;
branches;
next	1.21;

1.21
date	2000.11.13.15.18.08;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2000.07.22.04.45.09;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2000.07.21.00.24.37;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2000.04.11.14.43.54;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	2000.04.04.05.22.45;	author tgl;	state Exp;
branches;
next	1.15;

1.15
date	2000.03.27.17.14.43;	author thomas;	state Exp;
branches;
next	1.14;

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

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

1.12
date	99.07.22.15.09.13;	author thomas;	state Exp;
branches;
next	1.11;

1.11
date	99.07.06.17.16.40;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	99.06.14.07.37.04;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	99.05.27.16.29.02;	author momjian;	state Exp;
branches;
next	1.8;

1.8
date	99.01.21.22.53.36;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	98.12.29.02.24.44;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.11.14.02.04.16;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.10.30.19.34.31;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.10.10.17.13.45;	author thomas;	state Exp;
branches;
next	1.3;

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

1.2
date	98.10.06.03.12.59;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	98.10.05.02.54.43;	author thomas;	state Exp;
branches;
next	;

1.62.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;

1.65.2.1
date	2003.11.04.09.45.30;	author petere;	state Exp;
branches;
next	1.65.2.2;

1.65.2.2
date	2004.10.21.22.49.04;	author tgl;	state Exp;
branches;
next	1.65.2.3;

1.65.2.3
date	2008.08.26.00.03.52;	author tgl;	state Exp;
branches;
next	;

1.76.4.1
date	2008.08.26.00.03.43;	author tgl;	state Exp;
branches;
next	;

1.81.2.1
date	2006.04.15.18.11.48;	author momjian;	state Exp;
branches;
next	1.81.2.2;

1.81.2.2
date	2006.05.13.16.20.21;	author momjian;	state Exp;
branches;
next	1.81.2.3;

1.81.2.3
date	2006.05.13.17.11.02;	author momjian;	state Exp;
branches;
next	1.81.2.4;

1.81.2.4
date	2008.08.26.00.03.36;	author tgl;	state Exp;
branches;
next	;

1.92.2.1
date	2007.02.20.18.11.17;	author momjian;	state Exp;
branches;
next	1.92.2.2;

1.92.2.2
date	2007.03.26.17.23.44;	author tgl;	state Exp;
branches;
next	1.92.2.3;

1.92.2.3
date	2008.08.26.00.03.30;	author tgl;	state Exp;
branches;
next	;

1.98.2.1
date	2008.08.21.22.26.12;	author momjian;	state Exp;
branches;
next	1.98.2.2;

1.98.2.2
date	2008.08.26.00.03.24;	author tgl;	state Exp;
branches;
next	;

1.113.2.1
date	2009.08.07.20.55.05;	author alvherre;	state Exp;
branches;
next	;


desc
@@


1.118
log
@Add options to force quoting of all identifiers.

I've added a quote_all_identifiers GUC which affects the behavior
of the backend, and a --quote-all-identifiers argument to pg_dump
and pg_dumpall which sets the GUC and also affects the quoting done
internally by those applications.

Design by Tom Lane; review by Alex Hunsaker; in response to bug #5488
filed by Hartmut Goebel.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.117 2010/02/23 17:28:09 tgl Exp $
PostgreSQL documentation
-->

<refentry id="APP-PGDUMP">
 <refmeta>
  <refentrytitle>pg_dump</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_dump</refname>

  <refpurpose>
   extract a <productname>PostgreSQL</productname> database into a script file or other archive file
  </refpurpose>
 </refnamediv>

 <indexterm zone="app-pgdump">
  <primary>pg_dump</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_dump</command>
   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg><replaceable>dbname</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="pg-dump-description">
  <title>
   Description
  </title>

  <para>
   <application>pg_dump</application> is a utility for backing up a
   <productname>PostgreSQL</productname> database. It makes consistent
   backups even if the database is being used concurrently.
   <application>pg_dump</application> does not block other users
   accessing the database (readers or writers).
  </para>

  <para>
   Dumps can be output in script or archive file formats. Script
   dumps are plain-text files containing the SQL commands required
   to reconstruct the database to the state it was in at the time it was
   saved. To restore from such a script, feed it to <xref
   linkend="app-psql">. Script files
   can be used to reconstruct the database even on other machines and
   other architectures; with some modifications, even on other SQL
   database products.
  </para>

  <para>
   The alternative archive file formats must be used with
   <xref linkend="app-pgrestore"> to rebuild the database.  They
   allow <application>pg_restore</application> to be selective about
   what is restored, or even to reorder the items prior to being
   restored.
   The archive file formats are designed to be portable across
   architectures.
  </para>

  <para>
   When used with one of the archive file formats and combined with
   <application>pg_restore</application>,
   <application>pg_dump</application> provides a flexible archival and
   transfer mechanism. <application>pg_dump</application> can be used to
   backup an entire database, then <application>pg_restore</application>
   can be used to examine the archive and/or select which parts of the
   database are to be restored. 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 <application>tar</application> format
   (<option>-Ft</option>) is not compressed and has restrictions on
   reordering data when loading, but it is otherwise quite flexible;
   moreover, it can be manipulated with standard Unix tools such as
   <command>tar</command>.
  </para>

  <para>
   While running <application>pg_dump</application>, one should examine the
   output for any warnings (printed on standard error), especially in
   light of the limitations listed below.
  </para>

 </refsect1>

 <refsect1 id="pg-dump-options">
  <title>Options</title>

  <para>
    The following command-line options control the content and
    format of the output.

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">dbname</replaceable></term>
      <listitem>
       <para>
        Specifies the name of the database to be dumped.  If this is
        not specified, the environment variable
        <envar>PGDATABASE</envar> is used.  If that is not set, the
        user name specified for the connection is used.
       </para>
      </listitem>
     </varlistentry>

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

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-b</></term>
      <term><option>--blobs</></term>
      <listitem>
       <para>
        Include large objects in the dump.  This is the default behavior
        except when <option>--schema</>, <option>--table</>, or
        <option>--schema-only</> is specified, so the <option>-b</>
        switch is only useful to add large objects to selective dumps.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c</option></term>
      <term><option>--clean</option></term>
      <listitem>
       <para>
        Output commands to clean (drop)
        database objects prior to (the commands for) creating them.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-C</></term>
      <term><option>--create</></term>
      <listitem>
       <para>
        Begin the output with a command to create the
        database itself and reconnect to the created database.  (With a
        script of this form, it doesn't matter which database you connect
        to before running the script.)
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
      <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
      <listitem>
       <para>
        Create the dump in the specified character set encoding. By default,
        the dump is created in the database encoding.  (Another way to get the
        same result is to set the <envar>PGCLIENTENCODING</envar> environment
        variable to the desired dump encoding.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-f <replaceable class="parameter">file</replaceable></option></term>
      <term><option>--file=<replaceable class="parameter">file</replaceable></option></term>
      <listitem>
       <para>
        Send output to the specified file.  If this is omitted, the
        standard output is used.
       </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>
        Selects the format of the output.
        <replaceable>format</replaceable> can be one of the following:

       <variablelist>
        <varlistentry>
         <term><literal>p</></term>
         <term><literal>plain</></term>
         <listitem>
          <para>
           Output a plain-text <acronym>SQL</acronym> script file (the default).
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>c</></term>
         <term><literal>custom</></term>
         <listitem>
          <para>
           Output a custom-format archive suitable for input into
           <application>pg_restore</application>.
           This is the most flexible output format in that it allows manual
           selection and reordering of archived items during restore.
           This format is also compressed by default.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term><literal>t</></term>
         <term><literal>tar</></term>
         <listitem>
          <para>
           Output a <command>tar</command>-format archive suitable for input
           into <application>pg_restore</application>.
           This output format allows manual selection and reordering of
           archived items during restore, but there is a restriction: the
           relative order of table data items cannot be changed during
           restore.  Also, <command>tar</command> format does not support
           compression and has a limit of 8 GB on the size of individual
           tables.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>
       </para>

      </listitem>
     </varlistentry>

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

     <varlistentry>
      <term><option>-n <replaceable class="parameter">schema</replaceable></option></term>
      <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
      <listitem>
       <para>
        Dump only schemas matching <replaceable
        class="parameter">schema</replaceable>; this selects both the
        schema itself, and all its contained objects.  When this option is
        not specified, all non-system schemas in the target database will be
        dumped.  Multiple schemas can be
        selected by writing multiple <option>-n</> switches.  Also, the
        <replaceable class="parameter">schema</replaceable> parameter is
        interpreted as a pattern according to the same rules used by
        <application>psql</>'s <literal>\d</> commands (see <xref
        linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">),
        so multiple schemas can also be selected by writing wildcard characters
        in the pattern.  When using wildcards, be careful to quote the pattern
        if needed to prevent the shell from expanding the wildcards.
       </para>

       <note>
        <para>
         When <option>-n</> is specified, <application>pg_dump</application>
         makes no attempt to dump any other database objects that the selected
         schema(s) might depend upon. Therefore, there is no guarantee
         that the results of a specific-schema dump can be successfully
         restored by themselves into a clean database.
        </para>
       </note>

       <note>
        <para>
         Non-schema objects such as blobs are not dumped when <option>-n</> is
         specified.  You can add blobs back to the dump with the
         <option>--blobs</> switch.
        </para>
       </note>

      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-N <replaceable class="parameter">schema</replaceable></option></term>
      <term><option>--exclude-schema=<replaceable class="parameter">schema</replaceable></option></term>
      <listitem>
       <para>
        Do not dump any schemas matching the <replaceable
        class="parameter">schema</replaceable> pattern.  The pattern is
        interpreted according to the same rules as for <option>-n</>.
        <option>-N</> can be given more than once to exclude schemas
        matching any of several patterns.
       </para>

       <para>
        When both <option>-n</> and <option>-N</> are given, the behavior
        is to dump just the schemas that match at least one <option>-n</>
        switch but no <option>-N</> switches.  If <option>-N</> appears
        without <option>-n</>, then schemas matching <option>-N</> are
        excluded from what is otherwise a normal dump.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o</></term>
      <term><option>--oids</></term>
      <listitem>
       <para>
        Dump object identifiers (<acronym>OID</acronym>s) as part of the
        data for every table.  Use this option if your application references
        the <acronym>OID</>
        columns in some way (e.g., in a foreign key constraint).
        Otherwise, this option should not be used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-O</></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_dump</application> issues
        <command>ALTER OWNER</> or
        <command>SET SESSION AUTHORIZATION</command>
        statements to set ownership of created database objects.
        These statements
        will fail when the script is run unless it is started by a superuser
        (or the same user that owns all of the objects in the script).
        To make a script that can be restored by any user, but will give
        that user ownership of all the objects, specify <option>-O</>.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </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>
        Dump only the object definitions (schema), not data.
       </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.
        (Usually, it's better to leave this out, and instead start the
        resulting script as superuser.)
       </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>
        Dump only tables (or views or sequences) matching <replaceable
        class="parameter">table</replaceable>.  Multiple tables can be
        selected by writing multiple <option>-t</> switches.  Also, the
        <replaceable class="parameter">table</replaceable> parameter is
        interpreted as a pattern according to the same rules used by
        <application>psql</>'s <literal>\d</> commands (see <xref
        linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">),
        so multiple tables can also be selected by writing wildcard characters
        in the pattern.  When using wildcards, be careful to quote the pattern
        if needed to prevent the shell from expanding the wildcards.
       </para>

       <para>
        The <option>-n</> and <option>-N</> switches have no effect when
        <option>-t</> is used, because tables selected by <option>-t</> will
        be dumped regardless of those switches, and non-table objects will not
        be dumped.
       </para>

       <note>
        <para>
         When <option>-t</> is specified, <application>pg_dump</application>
         makes no attempt to dump any other database objects that the selected
         table(s) might depend upon. Therefore, there is no guarantee
         that the results of a specific-table dump can be successfully
         restored by themselves into a clean database.
        </para>
       </note>

       <note>
        <para>
         The behavior of the <option>-t</> switch is not entirely upward
         compatible with pre-8.2 <productname>PostgreSQL</productname>
         versions.  Formerly, writing <literal>-t tab</> would dump all
         tables named <literal>tab</>, but now it just dumps whichever one
         is visible in your default search path.  To get the old behavior
         you can write <literal>-t '*.tab'</>.  Also, you must write something
         like <literal>-t sch.tab</> to select a table in a particular schema,
         rather than the old locution of <literal>-n sch -t tab</>.
        </para>
       </note>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-T <replaceable class="parameter">table</replaceable></option></term>
      <term><option>--exclude-table=<replaceable class="parameter">table</replaceable></option></term>
      <listitem>
       <para>
        Do not dump any tables matching the <replaceable
        class="parameter">table</replaceable> pattern.  The pattern is
        interpreted according to the same rules as for <option>-t</>.
        <option>-T</> can be given more than once to exclude tables
        matching any of several patterns.
       </para>

       <para>
        When both <option>-t</> and <option>-T</> are given, the behavior
        is to dump just the tables that match at least one <option>-t</>
        switch but no <option>-T</> switches.  If <option>-T</> appears
        without <option>-t</>, then tables matching <option>-T</> are
        excluded from what is otherwise a normal dump.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</></term>
      <term><option>--verbose</></term>
      <listitem>
       <para>
        Specifies verbose mode.  This will cause
        <application>pg_dump</application> to output detailed object
        comments and start/stop times to the dump file, and progress
        messages to standard error.
       </para>
      </listitem>
     </varlistentry>

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

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

     <varlistentry>
      <term><option>-Z <replaceable class="parameter">0..9</replaceable></option></term>
      <term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
      <listitem>
       <para>
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--binary-upgrade</option></term>
      <listitem>
       <para>
        This option is for use by in-place upgrade utilities.  Its use
        for other purposes is not recommended or supported.  The
        behavior of the option may change in future releases without
        notice.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands (rather
        than <command>COPY</command>).  This will make restoration very slow;
        it is mainly useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        However, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
        Note that
        the restore might fail altogether if you have rearranged column order.
        The <option>--column-inserts</option> option is safe against column
        order changes, though even slower.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--column-inserts</option></term>
      <term><option>--attribute-inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands with explicit
        column names (<literal>INSERT INTO
        <replaceable>table</replaceable>
        (<replaceable>column</replaceable>, ...) VALUES
        ...</literal>).  This will make restoration very slow; it is mainly
        useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        However, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--disable-dollar-quoting</></term>
      <listitem>
       <para>
        This option disables the use of dollar quoting for function bodies,
        and forces them to be quoted using SQL standard string syntax.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--disable-triggers</></term>
      <listitem>
       <para>
        This option is only relevant when creating a data-only dump.
        It instructs <application>pg_dump</application> to include 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 be careful to
        start the resulting script as a superuser.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
      <listitem>
       <para>
        Do not wait forever to acquire shared table locks at the beginning of
        the dump. Instead fail if unable to lock a table within the specified
        <replaceable class="parameter">timeout</>. The timeout may be
        specified in any of the formats accepted by <command>SET
        statement_timeout</>.  (Allowed values vary depending on the server
        version you are dumping from, but an integer number of milliseconds
        is accepted by all versions since 7.3.  This option is ignored when
        dumping from a pre-7.3 server.)
       </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>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--use-set-session-authorization</></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.  Also, a dump using <command>SET SESSION AUTHORIZATION</>
        will certainly require superuser privileges to restore correctly,
        whereas <command>ALTER OWNER</> requires lesser privileges.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--quote-all-identifiers</></term>
      <listitem>
       <para>
        Force quoting of all identifiers.  This may be useful when dumping a
        database for migration to a future version that may have introduced
        additional keywords.
       </para>
      </listitem>
     </varlistentry>

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

    </variablelist>
   </para>

   <para>
    The following command-line options control the database 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_dump</application> to prompt for a
        password before connecting to a database.
       </para>

       <para>
        This option is never essential, since
        <application>pg_dump</application> will automatically prompt
        for a password if the server demands password authentication.
        However, <application>pg_dump</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 create the dump.
        This option causes <application>pg_dump</> 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_dump</>, 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
        dumps to be made without violating the policy.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATABASE</envar></term>
    <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-pgdump-diagnostics">
  <title>Diagnostics</title>

  <para>
   <application>pg_dump</application> internally executes
   <command>SELECT</command> statements. If you have problems running
   <application>pg_dump</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>

  <para>
   The database activity of <application>pg_dump</application> is
   normally collected by the statistics collector.  If this is
   undesirable, you can set parameter <literal>track_counts</literal>
   to false via <envar>PGOPTIONS</envar> or the <literal>ALTER
   USER</literal> command.
  </para>

 </refsect1>


 <refsect1 id="pg-dump-notes">
  <title>Notes</title>

  <para>
   If your database cluster has any local additions to the <literal>template1</> database,
   be careful to restore the output of <application>pg_dump</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>
   When a data-only dump is chosen and the option <option>--disable-triggers</>
   is used, <application>pg_dump</application> emits commands
   to disable triggers on user tables before inserting the data,
   and then 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>

  <para>
   Members of tar archives are limited to a size less than 8 GB.
   (This is an inherent limitation of the tar file format.)  Therefore
   this format cannot be used if the textual representation of any one table
   exceeds that size.  The total size of a tar archive and any of the
   other output formats is not limited, except possibly by the
   operating system.
  </para>

  <para>
   The dump file produced by <application>pg_dump</application>
   does not contain the statistics used by the optimizer to make
   query planning decisions.  Therefore, it is wise to run
   <command>ANALYZE</command> after restoring from a dump file
   to ensure optimal performance; see <xref linkend="vacuum-for-statistics">
   and <xref linkend="autovacuum"> for more information.
   The dump file also does not
   contain any <command>ALTER DATABASE ... SET</> commands;
   these settings are dumped by <xref linkend="app-pg-dumpall">,
   along with database users and other installation-wide settings.
  </para>

  <para>
   Because <application>pg_dump</application> is used to transfer data
   to newer versions of <productname>PostgreSQL</>, the output of
   <application>pg_dump</application> can be expected to load into
   <productname>PostgreSQL</> server versions newer than
   <application>pg_dump</>'s version.  <application>pg_dump</> can also
   dump from <productname>PostgreSQL</> servers older than its own version.
   (Currently, servers back to version 7.0 are supported.)
   However, <application>pg_dump</> cannot dump from
   <productname>PostgreSQL</> servers newer than its own major version;
   it will refuse to even try, rather than risk making an invalid dump.
   Also, it is not guaranteed that <application>pg_dump</>'s output can
   be loaded into a server of an older major version &mdash; not even if the
   dump was taken from a server of that version.  Loading a dump file
   into an older server may require manual editing of the dump file
   to remove syntax not understood by the older server.
  </para>
 </refsect1>

 <refsect1 id="pg-dump-examples">
  <title>Examples</title>

  <para>
   To dump a database called <literal>mydb</> into a SQL-script file:
<screen>
<prompt>$</prompt> <userinput>pg_dump mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   To reload such a script into a (freshly created) database named
   <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>psql -d newdb -f db.sql</userinput>
</screen>
  </para>

  <para>
   To dump a database into a custom-format archive file:

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

  <para>
   To reload an archive file into a (freshly created) database named
   <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput>
</screen>
  </para>

  <para>
   To dump a single table named <literal>mytab</>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -t mytab mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   To dump all tables whose names start with <literal>emp</> in the
   <literal>detroit</> schema, except for the table named
   <literal>employee_log</literal>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   To dump all schemas whose names start with <literal>east</> or
   <literal>west</> and end in <literal>gsm</>, excluding any schemas whose
   names contain the word <literal>test</>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   The same, using regular expression notation to consolidate the switches:

<screen>
<prompt>$</prompt> <userinput>pg_dump -n '(east|west)*gsm' -N '*test*' mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   To dump all database objects except for tables whose names begin with
   <literal>ts_</literal>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -T 'ts_*' mydb &gt; db.sql</userinput>
</screen>
  </para>

  <para>
   To specify an upper-case or mixed-case name in <option>-t</> and related
   switches, you need to double-quote the name; else it will be folded to
   lower case (see <xref
   linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">).  But
   double quotes are special to the shell, so in turn they must be quoted.
   Thus, to dump a single table with a mixed-case name, you need something
   like

<screen>
<prompt>$</prompt> <userinput>pg_dump -t '"MixedCaseName"' mydb &gt; mytab.sql</userinput>
</screen>
  </para>

 </refsect1>

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

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

</refentry>
@


1.117
log
@Clarify statements about tar archive format.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.116 2010/02/19 14:36:45 momjian Exp $
d664 11
@


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

Per report from Josh Kupershmidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.115 2010/02/19 03:50:03 momjian Exp $
d80 2
a81 2
   (<option>-Ft</option>) is not compressed and it is not possible to
   reorder data when loading, but it is otherwise quite flexible;
d227 5
a231 4
           Output a custom archive suitable for input into
           <application>pg_restore</application>. This is the most flexible
           format in that it allows reordering of loading data as well
           as object definitions. This format is also compressed by default.
d241 8
a248 5
           Output a <command>tar</command> archive suitable for input into
           <application>pg_restore</application>. Using this archive format
           allows reordering and/or exclusion of database objects
           at the time the database is restored. It is also possible to limit
           which data is reloaded at restore time.
@


1.115
log
@First pass over client applications documentation proofreading.

gabrielle
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.114 2009/08/07 20:54:31 alvherre Exp $
d487 10
d658 12
@


1.114
log
@Document that autovacuum may run ANALYZE
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.113 2009/03/22 16:44:26 tgl Exp $
d28 1
d55 1
a55 1
   other architectures; with some modifications even on other SQL
d534 1
a534 1
        Also, since this option generates a separate command for each row,
d557 1
a557 1
        Also, since this option generates a separate command for each row,
d640 1
a640 1
        ownership.  This makes the dump more standards compatible, but
d838 1
a838 1
   to ensure good performance; see <xref linkend="vacuum-for-statistics">
@


1.113
log
@Remove the -d and -D options of pg_dump and pg_dumpall.  The functionality
is still available, but you must now write the long equivalent --inserts
or --column-inserts.  This change is made to eliminate confusion with the
use of -d to specify a database name in most other Postgres client programs.
Original patch by Greg Mullane, modified per subsequent discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.112 2009/03/04 11:57:00 petere Exp $
d837 3
a839 1
   to ensure good performance.  The dump file also does not
@


1.113.2.1
log
@Document that autovacuum may run ANALYZE
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.113 2009/03/22 16:44:26 tgl Exp $
d837 1
a837 3
   to ensure good performance; see <xref linkend="vacuum-for-statistics">
   and <xref linkend="autovacuum"> for more information.
   The dump file also does not
@


1.112
log
@Provide some proper minimal documentation for the pg_dump(all) --binary-upgrade
option.  We don't want to commit to what it does, but hiding it will only
cause confusion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.111 2009/02/26 16:02:37 petere Exp $
a178 40
      <term><option>-d</option></term>
      <term><option>--inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands (rather
        than <command>COPY</command>).  This will make restoration very slow;
        it is mainly useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        Also, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
        Note that
        the restore might fail altogether if you have rearranged column order.
        The <option>-D</option> option is safe against column order changes,
        though even slower.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D</option></term>
      <term><option>--column-inserts</option></term>
      <term><option>--attribute-inserts</option></term>
      <listitem>
       <para>
        Dump data as <command>INSERT</command> commands with explicit
        column names (<literal>INSERT INTO
        <replaceable>table</replaceable>
        (<replaceable>column</replaceable>, ...) VALUES
        ...</literal>).  This will make restoration very slow; it is mainly
        useful for making dumps that can be loaded into
        non-<productname>PostgreSQL</productname> databases.
        Also, since this option generates a separate command for each row,
        an error in reloading a row causes only that row to be lost rather
        than the entire table contents.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d526 38
d815 1
a815 2
   <application>pg_dump</application> has a limitation; when a
   data-only dump is chosen and the option <option>--disable-triggers</>
d817 2
a818 2
   to disable triggers on user tables before inserting the data
   and commands to re-enable them after the data has been
d846 13
a858 6
   <application>pg_dump</application> can be loaded into
   newer <productname>PostgreSQL</> databases.  It also can read older
   <productname>PostgreSQL</> databases.  However, it usually cannot
   read newer <productname>PostgreSQL</> databases or produce dump output
   that can be loaded into older database versions.  To do this, manual
   editing of the dump file might be required.
@


1.111
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.110 2009/02/17 15:41:50 momjian Exp $
d554 12
a855 6

  <para>
   <application>pg_dump</application> also supports a
   <literal>--binary-upgrade</> option for upgrade utility usage.
  </para>

@


1.110
log
@Add pg_dump --binary-upgrade flag to be used by binary upgrade
utilities.

The new code allows transfer of dropped column information to the
upgraded server.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.109 2009/02/10 00:55:21 momjian Exp $
d682 15
@


1.109
log
@Update wording of how to prevent pg_dump from affecting statistics
collection.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.108 2009/02/07 15:25:51 momjian Exp $
d830 5
@


1.108
log
@Properly wrap new pg_dump doc text.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.107 2009/02/07 14:31:30 momjian Exp $
d762 1
d766 3
a768 4
   undesirable, you can set parameters <literal>stats_block_level</literal>
   and <literal>stats_row_level</literal> to false via the
   <application>libpq</> <envar>PGOPTIONS</envar> environment variable,
   or via <literal>ALTER USER</literal>.
a770 1

@


1.107
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.106 2009/01/05 16:54:36 tgl Exp $
d763 6
a768 3
   The database activity of <application>pg_dump</application> is normally collected by the statistics collector.
   If this is undesirable, you can set parameters <literal>stats_block_level</literal> and <literal>stats_row_level</literal> to false
   via the <application>libpq</> <envar>PGOPTIONS</envar> environment variable, or via <literal>ALTER USER</literal>.
@


1.106
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.105 2008/08/26 00:03:15 tgl Exp $
d729 1
d731 1
a732 1

d738 1
d762 7
@


1.105
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.104 2008/08/21 22:25:44 momjian Exp $
d701 17
@


1.104
log
@Mention that pg_dump does not dump ALTER DATABASE ... SET commands;
backpatch to 8.3.X. Also fix markup that had just one bullet.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.103 2008/07/20 18:43:30 tgl Exp $
d541 8
a548 3
        Specify the compression level to use in archive formats that
        support compression.  (Currently only the custom archive
        format supports compression.)
@


1.103
log
@Add a pg_dump option --lock-wait-timeout to allow failing the dump if unable
to acquire shared table locks within a specified amount of time.

David Gould
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.102 2008/04/13 03:49:21 tgl Exp $
d757 7
a763 16
   <application>pg_dump</application> has a few limitations:

   <itemizedlist>
    <listitem>
     <para>
      When a data-only dump is chosen and the option
      <option>--disable-triggers</> is used,
      <application>pg_dump</application> emits commands to disable
      triggers on user tables before inserting the data and 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>

   </itemizedlist>
d776 8
a783 5
   The dump file produced by <application>pg_dump</application> does
   not contain the statistics used by the optimizer to make query
   planning decisions.  Therefore, it is wise to run
   <command>ANALYZE</command> after restoring from a dump file to
   ensure good performance.
@


1.102
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.101 2008/03/26 16:34:47 tgl Exp $
a418 17
      <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>

       <para>
        This option is only meaningful for the plain-text format.  For
        the archive formats, you can specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d537 12
d555 2
a556 2
     </listitem>
    </varlistentry>
d586 33
a631 12

     <varlistentry>
      <term><option>-Z <replaceable class="parameter">0..9</replaceable></option></term>
      <term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
      <listitem>
       <para>
        Specify the compression level to use in archive formats that
        support compression.  (Currently only the custom archive
        format supports compression.)
       </para>
      </listitem>
     </varlistentry>
d682 1
a682 1
        password before connecting to a database.  
@


1.101
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.100 2008/03/26 14:32:22 momjian Exp $
d299 1
a299 14
        Ignore version mismatch between
        <application>pg_dump</application> and the database server.
       </para>

       <para>
        By default, <application>pg_dump</> will refuse to attempt
        to dump from a server that is of a newer <productname>PostgreSQL</>
        version than <application>pg_dump</application> is.  It will also
        refuse to attempt to dump from a server that is older than the oldest
        supported version (currently, 7.0).  The <option>-i</> option
        overrides this check and forces a dump to be attempted anyway.
        This option is <emphasis>deprecated</> because the dump is very
        likely to fail &mdash; or worse, seem to succeed but be wrong or
        incomplete.
@


1.100
log
@Strengthen warnings about using pg_dump's -i option.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.99 2008/03/20 17:36:57 tgl Exp $
d299 1
a299 1
        Ignore incompatible version check between
d304 9
a312 7
        Dumping from a server newer than <application>pg_dump</application>
        is likely fail and is disabled by default.
        Also, while <application>pg_dump</application> can dump from servers running
        previous releases of <productname>PostgreSQL</>, some very old
        versions are not supported (currently, pre-7.0).
        Use this option if you need to override the version check, but
        be prepared for <application>pg_dump</application> to fail.
@


1.99
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.98 2007/12/11 19:57:32 tgl Exp $
d299 1
a299 1
        Ignore version mismatch between
a303 3
        <application>pg_dump</application> can dump from servers running
        previous releases of <productname>PostgreSQL</>, but very old
        versions are not supported anymore (currently, those prior to 7.0).
d305 6
a310 4
        is likely not to work at all.
        Use this option if you need to override the version check (and
        if <application>pg_dump</application> then fails, don't say
        you weren't warned).
@


1.98
log
@Make documentation of -W options more accurate and uniform.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.97 2007/03/26 17:23:36 tgl Exp $
d431 17
@


1.98.2.1
log
@Mention that pg_dump does not dump ALTER DATABASE ... SET commands;
backpatch to 8.3.X. Also fix markup that had just one bullet.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.98 2007/12/11 19:57:32 tgl Exp $
d736 16
a751 7
   <application>pg_dump</application> has a limitation; when a
   data-only dump is chosen and the option <option>--disable-triggers</>
   is used, <application>pg_dump</application> emits commands
   to disable triggers on user tables before inserting the data
   and 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.
d764 5
a768 8
   The dump file produced by <application>pg_dump</application>
   does not contain the statistics used by the optimizer to make
   query planning decisions.  Therefore, it is wise to run
   <command>ANALYZE</command> after restoring from a dump file
   to ensure good performance.  The dump file also does not
   contain any <command>ALTER DATABASE ... SET</> commands;
   these settings are dumped by <xref linkend="app-pg-dumpall">,
   along with database users and other installation-wide settings.
@


1.98.2.2
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.98.2.1 2008/08/21 22:26:12 momjian Exp $
d605 3
a607 8
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
@


1.97
log
@Fix seriously broken markup for libpq-envars cross-references.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.96 2007/02/20 18:10:58 momjian Exp $
d650 1
a650 1
        Connect as the given user.
d660 12
a671 2
        Force a password prompt.  This should happen automatically if
        the server requires password authentication.
@


1.96
log
@More clearly document that most PostgreSQL utilities support libpq
environment variables.  Backpatch to 8.2.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.95 2007/02/20 15:01:17 momjian Exp $
d689 2
a690 2
   also uses the environment variables supported by <xref 
   linkend="libpq-envars" endterm="libpq">.
@


1.95
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.94 2007/02/01 04:39:33 neilc Exp $
d686 7
d703 3
a705 1
   linkend="app-psql">.
a877 1
   <member>Environment Variables (<xref linkend="libpq-envars">)</member>
@


1.94
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.93 2007/01/31 23:26:04 momjian Exp $
a862 11
  <title>History</title>

  <para>
   The <application>pg_dump</application> utility first appeared in
   <application>Postgres95</application> release 0.02.  The
   non-plain-text output formats were introduced in
   <productname>PostgreSQL</productname> release 7.1.
  </para>
 </refsect1>

 <refsect1>
@


1.93
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.92 2006/11/28 22:54:18 tgl Exp $
d647 1
d650 1
a650 1
        Connect as the given user
d657 1
@


1.92
log
@Add an example showing how to cope with mixed-case names in pg_dump
switches.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.91 2006/10/23 18:10:32 petere Exp $
d123 1
a123 1
        the archive formats, you may specify the option when you
d153 1
a153 1
        the archive formats, you may specify the option when you
d172 1
a172 1
        the archive formats, you may specify the option when you
d191 1
a191 1
        the restore may fail altogether if you have rearranged column order.
d340 1
a340 1
         schema(s) may depend upon. Therefore, there is no guarantee
d413 1
a413 1
        the archive formats, you may specify the option when you
d481 1
a481 1
         table(s) may depend upon. Therefore, there is no guarantee
d579 1
a579 1
        the archive formats, you may specify the option when you
d592 1
a592 1
        depending on the history of the objects in the dump, may not restore
d725 1
a725 1
      restore is stopped in the middle, the system catalogs may be
@


1.92.2.1
log
@More clearly document that most PostgreSQL utilities support libpq
environment variables.  Backpatch to 8.2.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.92 2006/11/28 22:54:18 tgl Exp $
a683 7

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

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


1.92.2.2
log
@Fix seriously broken markup for libpq-envars cross-references.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.92.2.1 2007/02/20 18:11:17 momjian Exp $
d687 2
a688 2
   also uses the environment variables supported by <application>libpq</>
   (see <xref linkend="libpq-envars">).
@


1.92.2.3
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.92.2.2 2007/03/26 17:23:44 tgl Exp $
d605 3
a607 8
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
@


1.91
log
@Spellchecking and such
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.90 2006/10/09 23:36:58 tgl Exp $
d844 14
@


1.90
log
@Revise psql pattern-matching switches as per discussion.  The rule is now
to process all inclusion switches then all exclusion switches, so that the
behavior is independent of switch ordering.
Use of -T does not cause non-table objects to be suppressed.  And
the patterns are now interpreted the same way psql's \d commands do it,
rather than as pure regex commands; this allows for example -t schema.tab
to do what it should have been doing all along.  Re-enable the --blobs
switch to do something useful, ie, add back blobs into a dump they were
otherwise suppressed from.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.89 2006/10/07 20:59:04 petere Exp $
d751 1
a751 1
   Because <application>pg_dump</application> is used to tranfer data
@


1.89
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.88 2006/09/16 00:30:19 momjian Exp $
d17 1
a17 1
   extract a <productname>PostgreSQL</productname> database into a script file or other archive file 
d130 13
d186 5
a190 1
        non-<productname>PostgreSQL</productname> databases.  Note that
d192 2
a193 4
        The <option>-D</option> option is safer, though even slower.
        Also, while this option generates errors for invalid data, 
        it allows other <command>INSERT</command>s to continue loading
        data into the table.
d211 3
a213 3
        Also, while this option generates errors for invalid data, 
        it allows other <command>INSERT</command>s to continue loading
        data into the table.
d256 1
a256 1
           Output a plain-text <acronym>SQL</acronym> script file (default)
d266 4
a269 4
         Output a custom archive suitable for input into 
         <application>pg_restore</application>. This is the most flexible 
         format in that it allows reordering of loading data as well 
         as object definitions. This format is also compressed by default.
d279 5
a283 5
         Output a <command>tar</command> archive suitable for input into 
         <application>pg_restore</application>. Using this archive format 
         allows reordering and/or exclusion of database objects
         at the time the database is restored. It is also possible to limit 
         which data is reloaded at restore time.
d304 1
a304 1
        <application>pg_dump</application> can handle databases from
d306 3
a308 1
        versions are not supported anymore (currently prior to 7.0).
d321 13
a333 3
        Dump the contents of <replaceable class="parameter">schema</>
        only. If this option is not specified, all non-system schemas
        in the target database will be dumped.
d338 13
a350 5
         In this mode, <application>pg_dump</application> makes no
         attempt to dump any other database objects that objects in the
         selected schema may depend upon. Therefore, there is no
         guarantee that the results of a single-schema dump can be
         successfully restored by themselves into a clean database.
d353 23
d401 1
a401 1
        <command>ALTER OWNER</> or 
d458 10
a467 8
        Dump data for <replaceable class="parameter">table</replaceable>
        only. It is possible for there to be multiple tables with the same 
        name in different schemas; if that is the case, all matching tables 
        will be dumped. Also, if any POSIX regular expression character appears
        in the table name (<literal>([{\.?+</>, the string will be interpreted
        as a regular expression.  Note that when in regular expression mode, the
        string will not be anchored to the start/end unless <literal>^</> and
        <literal>$</> are used at the beginning/end of the string.
d471 4
a474 6
       The options <option>-t</>, <option>-T</>, <option>-n</>, and <option>-N</> 
       can be used together to achieve a high degree of control over what is
       dumped. Multiple arguments can be used, and are parsed in the order 
       given to build a list of valid tables and schemas. The schema options are 
       parsed first to create a list of schemas to dump, and then the table options 
       are parsed to only find tables in the matching schemas.
a476 33
       <para>For example, to dump a single table named <literal>pg_class</>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -t pg_class mydb &gt; db.out</userinput>
</screen>
       </para>

       <para>To dump all tables starting with <literal>employee</> in the 
       <literal>detroit</> schema, except for the table named <literal>employee_log</literal>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -n detroit -t ^employee -T employee_log mydb &gt; db.out</userinput>
</screen>
       </para>

       <para>To dump all schemas starting with <literal>east</> or <literal>west</> and ending in
       <literal>gsm</>, but not schemas that contain the letters <literal>test</>, except for 
       one named <literal>east_alpha_test_five</>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -n "^(east|west).*gsm$" -N test -n east_alpha_test_five mydb &gt; db.out</userinput>
</screen>
       </para>


       <para>To dump all tables except for those beginning with <literal>ts_</literal>:

<screen>
<prompt>$</prompt> <userinput>pg_dump -T "^ts_" mydb &gt; db.out</userinput>
</screen>
       </para>


d479 3
a481 3
         In this mode, <application>pg_dump</application> makes no
         attempt to dump any other database objects that the selected tables
         may depend upon. Therefore, there is no guarantee
d486 13
d507 5
a511 3
        Do not dump any matching <replaceable class="parameter">tables</replaceable>.
        More than one option can be used, and POSIX regular expressions are handled just
        like <literal>-t</>.
a512 15
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-n <replaceable class="parameter">schema</replaceable></option></term>
      <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>
      <listitem>
       <para>
        Dump only the matching <replaceable class="parameter">schemas</replaceable>.
        More than one option can be used, and POSIX regular expressions are handled just
        like <literal>-t</>.
       </para>

      </listitem>
     </varlistentry>
a513 4
     <varlistentry>
      <term><option>-N <replaceable class="parameter">schema</replaceable></option></term>
      <term><option>--exclude-schema=<replaceable class="parameter">schema</replaceable></option></term>
      <listitem>
d515 5
a519 3
        Do not dump the matching <replaceable class="parameter">schemas</replaceable>.
        More than one option can be used, and POSIX regular expressions are handled just
        like <literal>-t</>.
a520 1

d531 1
a531 1
        comments and start/stop times to the dump file, and progress 
d767 10
a776 1
   To dump a database:
d778 1
a778 1
<prompt>$</prompt> <userinput>pg_dump mydb &gt; db.out</userinput>
d783 39
a821 1
   To reload this database:
d823 1
a823 1
<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
d828 1
a828 2
   To dump a database called <literal>mydb</> to a file in custom format:
   file:
d831 1
a831 1
<prompt>$</prompt> <userinput>pg_dump -Fc mydb &gt; db.out</userinput>
d836 2
a837 1
   To reload this dump into an existing database called <literal>newdb</>:
d840 1
a840 1
<prompt>$</prompt> <userinput>pg_restore -d newdb db.out</userinput>
@


1.88
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.87 2006/08/01 18:05:04 momjian Exp $
a526 1
      <term><option>-X disable-dollar-quoting</></term>
a536 1
      <term><option>-X disable-triggers</></term>
a563 1
      <term><option>-X use-set-session-authorization</></term>
@


1.87
log
@Allow multiple -n (schema) and -t (table)  pg_dump options, and add -T
and -N options to exclude objects.  Also support regular expressions for
option object names.

Greg Sabino Mullane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.86 2006/05/13 17:10:35 momjian Exp $
a802 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.86
log
@Update pg_dump vesion wording.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.85 2006/05/13 16:19:54 momjian Exp $
d401 7
a407 4
        only. It is possible for there to be
        multiple tables with the same name in different schemas; if that
        is the case, all matching tables will be dumped.  Specify both
        <option>--schema</> and <option>--table</> to select just one table.
d410 42
d455 1
a455 1
         attempt to dump any other database objects that the selected table
d457 1
a457 1
         that the results of a single-table dump can be successfully
d465 38
@


1.85
log
@Mention version portability of pg_dump.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.84 2006/05/06 23:25:37 momjian Exp $
d652 1
a652 1
   newer versions of <productname>PostgreSQL</>.  It also can read older
@


1.84
log
@Recommend more clearly custom pg_dump format over tar, buy showing
custom format examples first.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.83 2006/04/15 18:11:16 momjian Exp $
d648 11
@


1.83
log
@Document that pg_dump -d/-D prevents invalid data from canceling the
entire table load.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.82 2006/03/17 16:02:47 petere Exp $
d247 13
a272 13
        <varlistentry>
         <term><literal>c</></term>
         <term><literal>custom</></term>
         <listitem>
          <para>
         Output a custom archive suitable for input into 
         <application>pg_restore</application>. This is the most flexible 
         format in that it allows reordering of loading data as well 
         as object definitions. This format is also compressed by default.
          </para>
         </listitem>
        </varlistentry>

d668 1
a668 1
   To dump a database called <literal>mydb</> to a <filename>tar</filename>
d672 1
a672 1
<prompt>$</prompt> <userinput>pg_dump -Ft mydb &gt; db.tar</userinput>
d680 1
a680 1
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
@


1.82
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.81 2005/11/01 21:09:50 tgl Exp $
d176 3
d196 3
@


1.81
log
@Make an editorial pass over the reference pages.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.80 2005/07/25 22:12:31 tgl Exp $
d232 1
d242 1
d256 1
@


1.81.2.1
log
@Document that pg_dump -d/-D prevents invalid data from canceling the
entire table load.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.81 2005/11/01 21:09:50 tgl Exp $
a175 3
        Also, while this option generates errors for invalid data, 
        it allows other <command>INSERT</command>s to continue loading
        data into the table.
a192 3
        Also, while this option generates errors for invalid data, 
        it allows other <command>INSERT</command>s to continue loading
        data into the table.
@


1.81.2.2
log
@Mention version portability of pg_dump.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.81.2.1 2006/04/15 18:11:48 momjian Exp $
a644 11
  <para>
   Because <application>pg_dump</application> is used to tranfer data
   to newer versions of <productname>PostgreSQL</>, the output of
   <application>pg_dump</application> can be loaded into
   newer versions of <productname>PostgreSQL</>.  It also can read older
   <productname>PostgreSQL</> databases.  However, it usually cannot
   read newer <productname>PostgreSQL</> databases or produce dump output
   that can be loaded into older database versions.  To do this, manual
   editing of the dump file might be required.
  </para>

@


1.81.2.3
log
@Update pg_dump version wording.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.81.2.2 2006/05/13 16:20:21 momjian Exp $
d649 1
a649 1
   newer <productname>PostgreSQL</> databases.  It also can read older
@


1.81.2.4
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.81.2.3 2006/05/13 17:11:02 momjian Exp $
d500 3
a502 8
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
@


1.80
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.79 2005/07/10 15:08:52 momjian Exp $
d197 11
a207 9
	 <varlistentry>
	  <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
	  <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
	  <listitem>
	   <para>
	    Create the dump in the specified encoding. By default, the dump is
		created in the database encoding.
	   </para>
	  </listitem>
a209 1

d478 7
a484 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.79
log
@Add --encoding to pg_dump.

The Problem:  Occassionally a DBA needs to dump a database to a new
encoding.   In instances where the current encoding, (or lack of an
encoding, like SQL_ASCII) is poorly supported on the target  database
server, it can be useful to dump into a particular  encoding.  But,
currently the only way to set the encoding of  a pg_dump file is to
change  client_encoding in postgresql.conf and restart postmaster.
This is more  than a little awkward for production systems.

Magnus Hagander
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.78 2005/06/21 20:45:43 tgl Exp $
d477 2
a478 2
        Output SQL standard SET SESSION AUTHORIZATION commands instead
        of OWNER TO commands.  This makes the dump more standards compatible,
@


1.78
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
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.77 2005/05/29 03:32:18 momjian Exp $
d197 12
@


1.77
log
@Add reference to libpq environment variables for client applications.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.76 2005/01/17 04:30:37 neilc Exp $
d63 2
a64 3
   restored.  The archive formats also allow saving and restoring
   <quote>large objects</>, which is not possible in a script dump.
   The archive files are also designed to be portable across
a129 11
      <term><option>-b</></term>
      <term><option>--blobs</></term>
      <listitem>
       <para>
        Include large objects in the dump.  A non-text output format
        must be selected.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
a592 8
      When dumping a single table or as plain text, <application>pg_dump</application> 
      does not handle large objects. Large objects must be dumped with the
      entire database using one of the non-text archive formats.
     </para>
    </listitem>

    <listitem>
     <para>
d643 2
a644 2
   To dump a database called <literal>mydb</> that contains
   large objects to a <filename>tar</filename> file:
d647 1
a647 1
<prompt>$</prompt> <userinput>pg_dump -Ft -b mydb &gt; db.tar</userinput>
d652 1
a652 2
   To reload this database (with large objects) to an
   existing database called <literal>newdb</>:
@


1.76
log
@Fix minor thinko in pg_dump documentation of "-n" option.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.75 2005/01/04 03:58:16 tgl Exp $
d700 1
@


1.76.4.1
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.76 2005/01/17 04:30:37 neilc Exp $
d490 3
a492 8
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
@


1.75
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.74 2004/10/21 22:48:54 tgl Exp $
d290 1
a290 1
      <term><option>-n <replaceable class="parameter">namespace</replaceable></option></term>
@


1.74
log
@Update obsolete comments about COPY vs INSERT options, per Uwe Schroeder.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.73 2004/07/13 02:59:49 momjian Exp $
d48 2
a49 2
   Dumps can be output in script or archive file formats. The script
   files are in plain-text format and contain the SQL commands required
d51 2
a52 1
   saved. To restore these scripts, use <xref linkend="app-psql">. They
d54 1
a54 1
   other architectures, with some modifications even on other SQL
d59 2
a60 2
   The alternative archive file formats that are meant to be used with
   <xref linkend="app-pgrestore"> to rebuild the database, and they also
d63 3
a65 1
   restored. The archive files are also designed to be portable across
d82 1
a82 1
   moreover, it can be manipulated with other tools such as
d98 2
a99 1
   The following command-line options are used to control the output format.
d106 4
a109 4
	Specifies the name of the database to be dumped.  If this is
	not specified, the environment variable
	<envar>PGDATABASE</envar> is used.  If that is not set, the
	user name specified for the connection is used.
d119 1
a119 1
	Dump only the data, not the object definitions (schema)
d124 1
a124 1
        the other formats, you may specify the option when you
d135 2
a136 1
 	Include large objects in dump.
d147 1
a147 1
	database objects prior to (the commands for) creating them.
d152 1
a152 1
        the other formats, you may specify the option when you
d163 4
a166 4
	Begin the output with a command to create the
	database itself and reconnect to the created database.  (With a
	script of this form, it doesn't matter which database you connect
	to before running the script.)
d171 1
a171 1
        the other formats, you may specify the option when you
d182 6
a187 6
	Dump data as <command>INSERT</command> commands (rather
	than <command>COPY</command>).  This will make restoration very slow;
	it is mainly useful for making dumps that can be loaded into
	non-<productname>PostgreSQL</productname> databases.  Note that
	the restore may fail altogether if you have rearranged column order.
	The <option>-D</option> option is safer, though even slower.
d198 7
a204 7
	Dump data as <command>INSERT</command> commands with explicit
	column names (<literal>INSERT INTO
	<replaceable>table</replaceable>
	(<replaceable>column</replaceable>, ...) VALUES
	...</literal>).  This will make restoration very slow; it is mainly
	useful for making dumps that can be loaded into
	non-<productname>PostgreSQL</productname> databases.
d214 2
a215 2
	Send output to the specified file.  If this is omitted, the
	standard output is used.
d226 1
a226 1
	<replaceable>format</replaceable> can be one of the following:
d303 1
a303 1
	 selected schema may depend upon. Therefore, there is no
d316 5
a320 4
	Dump object identifiers (<acronym>OID</acronym>s) for every
	table.  Use this option if your application references the <acronym>OID</>
	columns in some way (e.g., in a foreign key constraint).
	Otherwise, this option should not be used.
d331 10
a340 9
	ownership of objects to match the original database.
	By default, <application>pg_dump</application> issues
	<command>SET SESSION AUTHORIZATION</command>
	statements to set ownership of created database objects.
	These statements
	will fail when the script is run unless it is started by a superuser
	(or the same user that owns all of the objects in the script).
	To make a script that can be restored by any user, but will give
	that user ownership of all the objects, specify <option>-O</>.
d345 1
a345 1
        the other formats, you may specify the option when you
d357 1
a357 1
	compatibility.
d367 1
a367 1
	Dump only the object definitions (schema), not data.
d378 3
a380 3
	This is only relevant if <option>--disable-triggers</> is used.
	(Usually, it's better to leave this out, and instead start the
	resulting script as superuser.)
d390 5
a394 5
	Dump data for <replaceable class="parameter">table</replaceable>
	only. It is possible for there to be
	multiple tables with the same name in different schemas; if that
	is the case, all matching tables will be dumped.  Specify both
	<option>--schema</> and <option>--table</> to select just one table.
d401 1
a401 1
	 may depend upon. Therefore, there is no guarantee
d414 2
a415 2
	Specifies verbose mode.  This will cause
	<application>pg_dump</application> to output detailed object
d428 1
a428 1
	Prevent dumping of access privileges (grant/revoke commands).
d466 1
a466 1
        the other formats, you may specify the option when you
d477 4
a480 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.
d522 4
a525 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.
d629 1
a629 1
   this format cannot be used if the textual representation of a table
@


1.73
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
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.72 2004/07/10 15:51:28 momjian Exp $
d178 5
a182 3
	than <command>COPY</command>). This will make restoration very
	slow, but it makes the archives more portable to other SQL database
	management systems.
d197 3
a199 2
	...</literal>).  This will make restoration very slow,
	but it is necessary if you desire to rearrange the column ordering.
@


1.72
log
@Clarify schema meanings in pg_dump manual page by referring to object
definitions more frequently.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.71 2004/06/07 20:35:57 momjian Exp $
d467 4
a470 4
        This option is obsolete but still accepted for backwards
        compatibility.
        <application>pg_dump</application> now always behaves in the
        way formerly selected by this option.
@


1.71
log
@Add start/stop times for pg_dump/pg_dumpall when verbose output is used.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.70 2004/05/31 13:37:52 momjian Exp $
d115 1
a115 1
	Dump only the data, not the schema (data definitions).
d236 1
a236 1
         allows reordering and/or exclusion of schema elements 
d249 2
a250 2
         format in that it allows reordering of data load as well 
         as schema elements. This format is also compressed by default.
d325 1
a325 1
	statements to set ownership of created schema elements.
d357 1
a357 1
	Dump only the schema (data definitions), no data.
@


1.70
log
@Update pg_dump -v comments to mention additional comments in dump file.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.69 2004/03/23 22:06:08 tgl Exp $
d406 2
a407 1
        comments in the dump file, and progress messages to standard error.
@


1.69
log
@Use dollar-quoting for function bodies, unless disabled with
--disable-dollar-quoting.

Andrew Dunstan
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.68 2003/12/01 22:07:58 momjian Exp $
d405 2
a406 2
	<application>pg_dump</application> to print progress messages
	to standard error.
@


1.68
log
@This patch adds a new GUC var, "default_with_oids", which follows the
proposal for eventually deprecating OIDs on user tables that I posted
earlier to pgsql-hackers. pg_dump now always specifies WITH OIDS or
WITHOUT OIDS when dumping a table. The documentation has been updated.

Neil Conway
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.67 2003/11/29 19:51:39 pgsql Exp $
d423 2
a424 2
      <term><option>-X use-set-session-authorization</></term>
      <term><option>--use-set-session-authorization</></term>
d427 2
a428 4
        This option is obsolete but still accepted for backwards
	compatibility.
        <application>pg_dump</application> now always behaves in the
	way formerly selected by this option.
d430 2
a431 2
      </listitem>
     </varlistentry>
d439 5
a443 5
	It instructs <application>pg_dump</application> to include 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.
d448 3
a450 3
	must be done as superuser.  So, you should also specify
	a superuser name with <option>-S</>, or preferably be careful to
	start the resulting script as a superuser.
d462 13
d479 3
a481 3
	Specify the compression level to use in archive formats that
	support compression.  (Currently only the custom archive
	format supports compression.)
@


1.67
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.66 2003/11/04 09:55:39 petere Exp $
d614 5
a618 2
   Once restored, it is wise to run <command>ANALYZE</> on each
   restored table so the optimizer has useful statistics.
@


1.66
log
@Random copy-editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.65 2003/09/23 22:48:53 tgl Exp $
@


1.65
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
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.64 2003/09/11 21:42:20 momjian Exp $
d180 1
a180 1
	packages.
@


1.65.2.1
log
@Random copy-editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.65 2003/09/23 22:48:53 tgl Exp $
d180 1
a180 1
	management systems.
@


1.65.2.2
log
@Update obsolete comments about COPY vs INSERT options, per Uwe Schroeder.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.65.2.1 2003/11/04 09:45:30 petere Exp $
d178 3
a180 5
	than <command>COPY</command>).  This will make restoration very slow;
	it is mainly useful for making dumps that can be loaded into
	non-<productname>PostgreSQL</productname> databases.  Note that
	the restore may fail altogether if you have rearranged column order.
	The <option>-D</option> option is safer, though even slower.
d195 2
a196 3
	...</literal>).  This will make restoration very slow; it is mainly
	useful for making dumps that can be loaded into
	non-<productname>PostgreSQL</productname> databases.
@


1.65.2.3
log
@Fix pg_dump docs to acknowledge that you can use -Z with plain text output.  Pointed out by Daniel Migowski.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.65.2.2 2004/10/21 22:49:04 tgl Exp $
d471 3
a473 8
        Specify the compression level to use.  Zero means no compression.
        For the custom archive format, this specifies compression of
        individual table-data segments, and the default is to compress
        at a moderate level.
        For plain text output, setting a nonzero compression level causes
        the entire output file to be compressed, as though it had been
        fed through <application>gzip</>; but the default is not to compress.
        The tar archive format currently does not support compression at all.
@


1.64
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
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.63 2003/08/31 17:32:23 petere Exp $
d321 10
a330 10
        Do not output commands to set the
	object ownership to match the original database.  Typically,
	<application>pg_dump</application> issues
	(<application>psql</application>-specific) <command>\connect</command>
	statements to set ownership of schema elements.  See also
	under <option>-R</option> and <option>-X
	use-set-session-authorization</option>.  Note that
	<option>-O</option> does not prevent all reconnections to the
	database, only the ones that are exclusively used for
	ownership adjustments.
d346 2
a347 21
	Prohibit <application>pg_dump</application>
        from outputting a script that would require reconnections to
        the database while being restored.  An average restoration
        script usually has to reconnect several times as different
        users to set the original ownerships of the objects.  This
        option is a rather blunt instrument because it makes
        <application>pg_dump</application> lose this ownership information,
        <emphasis>unless</emphasis> you use the <option>-X
        use-set-session-authorization</option> option.
       </para>

       <para>
        One possible reason why reconnections during restore might not
        be desired is if the access to the database requires manual
        interaction (e.g., passwords).
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
d369 1
a369 2
	(Usually, it's better to specify
	<option>--use-set-session-authorization</>, and then start the
d427 4
a430 26
        Normally, if a (plain-text mode) script generated by
        <application>pg_dump</application> must alter the current database
        user (e.g., to set correct object ownerships), it uses the
        <application>psql</application> <command>\connect</command> command.
        This command actually opens a new connection, which might
        require manual interaction (e.g., passwords).  If you use the
        <option>-X use-set-session-authorization</option> option, then
        <application>pg_dump</application> will instead output <xref
        linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> commands.  This has
        the same effect, but it requires that the user restoring the
        database from the generated script be a database superuser.
        This option effectively overrides the <option>-R</option>
        option.
       </para>

       <para>
        Since <xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> is a
        standard SQL command, whereas <command>\connect</command> only
        works in <application>psql</application>, this option also enhances
        the theoretical portability of the output script.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
d451 2
a452 4
	a superuser name with <option>-S</>, or preferably specify
	<option>--use-set-session-authorization</> and then be careful to
	start the resulting script as a superuser.  If you give neither
	option, the entire script must be run as superuser.
@


1.63
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.62 2003/06/11 16:29:42 tgl Exp $
d708 1
a708 1
   <application>PostgreSQL</application> release 7.1.
@


1.62
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
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.61 2003/04/17 15:34:37 momjian Exp $
d20 4
@


1.62.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.63 2003/08/31 17:32:23 petere Exp $
a19 4

 <indexterm zone="app-pgdump">
  <primary>pg_dump</primary>
 </indexterm>
@


1.61
log
@Make pg_dump's concurency capability more prominent.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.60 2003/03/25 16:15:42 petere Exp $
d290 3
a292 3
         attempt to dump any other database objects that may depend
         upon objects in the selected schema. Therefore, there is no
         guarantee that the results of a single schema dump can be
d397 1
a397 2
	only. If <literal>*</literal> is specified, all tables in the
	specified database will be dumped. It is possible for there to be
d399 2
a400 1
	is the case, all matching tables will be dumped.
d406 3
a408 3
         attempt to dump any other database objects that may depend
         upon the selected table. Therefore, there is no guarantee
         that the results of a single table dump can be successfully
d655 1
a655 1
   restored object so the optimizer has useful statistics.
@


1.60
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.59 2003/03/24 14:32:51 petere Exp $
d36 5
a40 9
   <application>pg_dump</application> is a utility for saving a
   <productname>PostgreSQL</productname> database into a script or an
   archive file.  The script files are in plain-text format and
   contain the SQL commands required to reconstruct the database to
   the state it was in at the time it was saved.  To restore these
   scripts, use <xref linkend="app-psql">.  They can be used to
   reconstruct the database even on other machines and other
   architectures, with some modifications even on other SQL database
   products.
d44 15
a58 6
   Furthermore, there are alternative archive file formats
   that are meant to be used with <xref linkend="app-pgrestore"> to
   rebuild the database, and they 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 also designed to be portable across
d64 2
a65 2
   <application>pg_restore</application>, <application>pg_dump</application> provides a
   flexible archival and 
d67 10
a76 10
   backup an entire database, then <application>pg_restore</application> can
   be used to examine the archive and/or select which parts of the
   database are to be restored.
   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
   <application>tar</application> format (<option>-Ft</option>) is not
   compressed and it is not possible to reorder data when loading, but
   it is otherwise quite flexible; moreover, it can be manipulated with
   other tools such as <command>tar</command>.
a84 6
  <para>
   <application>pg_dump</application> makes consistent backups even if the
   database is being used concurrently.  <application>pg_dump</application>
   does not block other users accessing the database (readers or
   writers).
  </para>
@


1.59
log
@Another big editing pass for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.58 2003/03/18 17:05:01 momjian Exp $
a715 1
   <member>&cite-admin;</member>
@


1.58
log
@Remove duplicate ANALYZE recommendation in pg_dump.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.57 2003/03/18 00:02:11 momjian Exp $
d24 1
a24 1
   <arg rep="repeat"><replaceable>options</replaceable></arg>
a57 8
   <application>pg_dump</application> will save the information 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 so that it can be readily copied in again, as well
   as imported into tools for editing.
  </para>

  <para>
d68 1
a68 1
   <filename>tar</filename> format (<option>-Ft</option>) is not
d71 1
a71 1
   other tools such as <filename>tar</filename>.
d75 1
a75 1
   While running <command>pg_dump</command>, one should examine the
d193 1
a193 1
	but it is necessary if you desire to rearrange column ordering.
d219 1
a219 1
         <term>p</term>
d228 1
a228 1
         <term>t</term>
d231 1
a231 1
         Output a <filename>tar</filename> archive suitable for input into 
d241 1
a241 1
         <term>c</term>
d509 3
a511 2
	Specify the compression level to use in archive formats that support 
      compression (currently only the custom archive format supports compression).
d527 5
a531 3
	Specifies the host name of the machine on which the server is
	running.  If the host name begins with a slash, it is used as the
	directory for the Unix domain socket.
d541 4
a544 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).
d593 7
a599 36
  <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_dump</application> could not connect to the
	PostgreSQL server 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.
       </para>
    </msgexplan>
   </msgentry>

  </msgset>

   <note>
    <para>
     <application>pg_dump</application> internally executes
     <command>SELECT</command> statements. If you have problems running
     <application>pg_dump</application>,
     make sure you are able to select information from the database using, for
     example, <xref linkend="app-psql">.
    </para>
   </note>
d607 1
a607 1
   If your installation has any local additions to the template1 database,
d611 1
a611 1
   without any local additions, copy from template0 not template1,
d625 2
a626 2
      does not handle large objects. Large objects must be dumped in their
      entirety using one of the binary archive formats.
d632 7
a638 4
      When doing a data-only dump, <application>pg_dump</application> emits queries
      to disable triggers on user tables before inserting the data and queries to
      re-enable them after the data has been inserted.  If the restore is stopped
      in the middle, the system catalogs may be left in the wrong state.
d703 1
a703 1
   <application>Postgres95</application> release <literal>0.02</literal>.  The
d705 1
a705 1
   <application>PostgreSQL</application> release <literal>7.1</literal>.
@


1.57
log
@Add mention of ANALYZE after object restore.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.56 2003/02/13 04:54:15 momjian Exp $
a651 5

   <para>
    Once restored, it is wise to run <command>ANALYZE</> on each
    restored object so the optimizer has useful statistics.
   </para>
@


1.56
log
@[ dumping schemas ]

> I don't care what you use for short options if all useful ones are taken.
> But the long option should be --schema.

Ok, fair enough: a revised patch is attached that uses the '-n' short
option and the '--schema' long option.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.55 2003/01/19 00:13:30 momjian Exp $
d653 5
d690 6
@


1.55
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
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.54 2003/01/06 18:53:24 petere Exp $
d287 22
d405 16
a420 2
	Dump data for <replaceable class="parameter">table</replaceable> only.
       </para>
d534 3
a536 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.
d589 1
a589 1
      Default connection parameters
d616 4
a619 5
	<application>pg_dump</application> could not attach to the 
	PostgreSQL server 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.
d667 1
a667 1
      When doing a data only dump, <application>pg_dump</application> emits queries
@


1.54
log
@Use our own version of getopt_long() if the OS doesn't have one.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.53 2002/11/15 03:11:18 momjian Exp $
d708 1
a708 1
   <member><citetitle>PostgreSQL Administrator's Guide</citetitle></member>
@


1.53
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.52 2002/10/11 23:03:48 petere Exp $
a539 4

  <para>
   Long option forms are only available on some platforms.
  </para>
@


1.52
log
@Assorted reference page updates
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.51 2002/09/07 16:14:33 petere Exp $
d277 5
a281 5
        previous releases of PostgreSQL, but very old versions are not
        supported anymore (currently prior to 7.0).  Use this option
        if you need to override the version check (and if
        <application>pg_dump</application> then fails, don't say you
        weren't warned).
d292 1
a292 1
	table.  Use this option if your application references the OID
@


1.51
log
@Allow pg_dumpall to work with previous releases again.  Don't pass the -c
option down to pg_dump, where it's useless, and clarify the meaning of -c
in the documentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.50 2002/09/06 21:58:36 petere Exp $
d24 1
a24 21
   <group> <arg>-a</arg> <arg>-s</arg> </group>
   <arg>-b</arg>
   <arg>-c</arg>
   <arg>-C</arg>
   <group> <arg>-d</arg> <arg>-D</arg> </group>
   <arg>-f <replaceable>file</replaceable></arg> 
   <arg>-F <replaceable>format</replaceable></arg>
   <arg>-i</arg>
   <arg>-o</arg>
   <arg>-O</arg>
   <arg>-R</arg>
   <arg>-S</arg>
   <arg>-t <replaceable>table</replaceable></arg>
   <arg>-v</arg>
   <arg>-x</arg>
   <arg>-X <replaceable>keyword</replaceable></arg>
   <arg>-Z <replaceable>0...9</replaceable></arg>
   <arg>-h <replaceable>host</replaceable></arg>
   <arg>-p <replaceable>port</replaceable></arg>
   <arg>-U <replaceable>username</replaceable></arg>
   <arg>-W</arg>
d36 1
a36 1
   <command>pg_dump</command> is a utility for saving a
d40 2
a41 1
   the state it was in at the time it was saved.  They can be used to
d43 11
a53 7
   architectures, with some modifications even on other RDBMS
   products.  Furthermore, there are alternative archive file formats that
   are meant to be
   used with <xref linkend="app-pgrestore"> to rebuild the database,
   and they 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 also designed to be portable across
d58 1
a58 1
   <command>pg_dump</command> will save the information necessary to
a65 6
   <command>pg_dump</command> 
   is useful for dumping out the contents of a database to move from one
   <productname>PostgreSQL</productname> installation to another.
  </para>

  <para>
d67 1
a67 1
   <xref linkend="app-pgrestore">, <command>pg_dump</command> provides a
d69 2
a70 2
   transfer mechanism. <command>pg_dump</command> can be used to
   backup an entire database, then <command>pg_restore</command> can
d89 2
a90 2
   <command>pg_dump</command> makes consistent backups even if the
   database is being used concurrently.  <command>pg_dump</command>
d184 1
a184 1
	slow, but it makes the archives more portable to other RDBMS
d240 1
a240 1
         <command>pg_restore</command>. Using this archive format 
d253 1
a253 1
         <command>pg_restore</command>. This is the most flexible 
d306 2
a307 2
	<command>pg_dump</command> issues
	(<command>psql</command>-specific) <command>\connect</command>
d329 1
a329 1
	Prohibit <command>pg_dump</command>
d335 1
a335 1
        <command>pg_dump</command> lose this ownership information,
d417 1
a417 1
        <command>pg_dump</command> must alter the current database
d419 1
a419 1
        <xref linkend="app-psql"> <command>\connect</command> command.
d423 1
a423 1
        <command>pg_dump</command> will instead output <xref
d434 1
a434 1
        works in <xref linkend="app-psql">, this option also enhances
d452 1
a452 1
	It instructs <command>pg_dump</command> to include commands
d573 1
a573 1
<screen><computeroutput>
d578 1
a578 1
</computeroutput></screen>
d585 3
a587 4
	<command>pg_dump</command> could not attach to the 
	<command>postmaster</command> 
	process on the specified host and port.  If you see this message,
	ensure that the <command>postmaster</command> 
d598 1
a598 1
     <command>pg_dump</command> internally executes
d600 1
a600 1
     <command>pg_dump</command>,
d613 1
a613 1
   be careful to restore the output of <command>pg_dump</command> into a
d619 1
a619 1
CREATE DATABASE foo WITH TEMPLATE = template0;
d624 1
a624 1
   <command>pg_dump</command> has a few limitations:
d629 1
a629 1
      When dumping a single table or as plain text, <command>pg_dump</command> 
d637 1
a637 1
      When doing a data only dump, <command>pg_dump</command> emits queries
d698 1
a698 1
   The <command>pg_dump</command> utility first appeared in
@


1.50
log
@Make sure the pg_dump tar archiver can handle members larger than 2 GB, but
does not create members larger than allowed by the tar format.  Also, fix
the generation of the tar header to conform to POSIX.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.49 2002/08/27 18:57:26 petere Exp $
d292 11
a302 8
        Ignore version mismatch between <command>pg_dump</command>
	and the database server.  Since <command>pg_dump</command>
	knows a great deal about system catalogs, any given version of
	<command>pg_dump</command> is only intended to work with
	the corresponding release of the database server.  Use this option
	if you need to override the version check (and if
	<command>pg_dump</command> then fails, don't
	say you weren't warned).
@


1.49
log
@Reimplement pg_dumpall in C.  Currently no change in functionality,
except that it's more robust, reconnects less often, and is NLS'ed.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.48 2002/08/18 09:36:25 petere Exp $
d664 9
@


1.48
log
@Make pg_dump output more portable and more pleasing to look at.

The -n and -N options were removed.  Quoting is now smart enough to
supply quotes if and only if necessary.

Numerical types are now printed without quotes, except in cases of
special values such as NaN.

Boolean values printed as true and false.

Most string literals now do not escape whitespace characters (newlines,
etc.) for portability.

SET SESSION AUTHORIZATION argument is a string literal, to follow SQL.

Made commands output by pg_dump use consistent spacing and indentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.47 2002/08/10 16:57:31 petere Exp $
d115 1
d117 2
a118 2
  <refsect2 id="pg-dump-options">
   <title>Options</title>
d120 2
a121 3
   <para>
    <command>pg_dump</command> accepts the following command
    line arguments.  (Long option forms are only available on some platforms.)
d411 3
a413 1
	Specifies verbose mode.
a503 2


d506 1
d508 1
a508 2
    <command>pg_dump</command> also accepts 
    the following command line arguments for connection parameters:
a557 1
  </refsect2>
d559 3
@


1.47
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
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/pg_dump.sgml,v 1.46 2002/07/28 15:22:20 petere Exp $
a31 1
   <group> <arg>-n</arg> <arg>-N</arg> </group>
a299 25
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-n</></term>
      <term><option>--no-quotes</></term>
      <listitem>
       <para>
	Suppress double quotes around identifiers unless absolutely necessary.
	This may cause trouble loading this dumped data if there are reserved words
	used for identifiers. 
	This was the default behavior for
	<command>pg_dump</command> prior to version 6.4.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-N</></term>
      <term><option>--quotes</></term>
      <listitem>
       <para>
	Include double quotes around identifiers.
	This is the default.
@


1.46
log
@Structure reference pages consistently.  Document that structure.
Add information about environment variables.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.45 2002/05/10 22:36:26 tgl Exp $
d46 1
a46 1
   <arg choice="plain"><replaceable>dbname</replaceable></arg>
d129 4
a132 1
	Specifies the name of the database to be dumped.
d568 1
a568 1
        Connect as the given user.
a593 9

    <listitem>
     <para>
      Database to dump, unless overridden on the command line.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
@


1.45
log
@First pass at schema-fying pg_dump/pg_restore.  Much to do still,
but the basic capability seems to work.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.44 2002/04/21 19:02:39 thomas Exp $
d583 28
@


1.44
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
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.43 2002/03/22 19:20:42 petere Exp $
d410 5
a414 4
        The scripts or archives created by <command>pg_dump</command>
        need to have superuser access in certain cases, such as when
        disabling triggers or setting ownership of schema elements.
        This option specifies the user name to use for those cases.
d475 30
@


1.43
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.42 2002/02/11 00:14:10 tgl Exp $
a6 4
 <docinfo>
  <date>2001-03-06</date>
 </docinfo>

d8 1
a8 3
  <refentrytitle>
   pg_dump
  </refentrytitle>
@


1.42
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
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.41 2001/12/08 03:24:37 thomas Exp $
d141 2
a142 2
      <term>-a</term>
      <term>--data-only</term>
d157 2
a158 2
      <term>-b</term>
      <term>--blobs</term>
d167 2
a168 2
      <term>-c</term>
      <term>--clean</term>
d184 2
a185 2
      <term>-C</term>
      <term>--create</term>
d203 2
a204 2
      <term>-d</term>
      <term>--inserts</term>
d216 3
a218 3
      <term>-D</term>
      <term>--column-inserts</term>
      <term>--attribute-inserts</term>
d232 2
a233 2
      <term>-f <replaceable class="parameter">file</replaceable></term>
      <term>--file=<replaceable class="parameter">file</replaceable></term>
d243 2
a244 2
      <term>-F <replaceable class="parameter">format</replaceable></term>
      <term>--format=<replaceable class="parameter">format</replaceable></term>
d292 2
a293 2
      <term>-i</term>
      <term>--ignore-version</term>
d309 2
a310 2
      <term>-n</term>
      <term>--no-quotes</term>
d323 2
a324 2
      <term>-N</term>
      <term>--quotes</term>
d334 2
a335 2
      <term>-o</term>
      <term>--oids</term>
d347 2
a348 2
      <term>-O</term>
      <term>--no-owner</term>
d372 2
a373 2
      <term>-R</term>
      <term>--no-reconnect</term>
d402 2
a403 2
      <term>-s</term>
      <term>--schema-only</term>
d412 2
a413 2
      <term>-S <replaceable class="parameter">username</replaceable></term>
      <term>--superuser=<replaceable class="parameter">username</replaceable></term>
d425 2
a426 2
      <term>-t <replaceable class="parameter">table</replaceable></term>
      <term>--table=<replaceable class="parameter">table</replaceable></term>
d435 2
a436 2
      <term>-v</term>
      <term>--verbose</term>
d445 3
a447 3
      <term>-x</term>
      <term>--no-privileges</term>
      <term>--no-acl</term>
d456 2
a457 2
      <term>-X use-set-session-authorization</term>
      <term>--use-set-session-authorization</term>
d491 2
a492 2
      <term>-Z <replaceable class="parameter">0..9</replaceable></term>
      <term>--compress=<replaceable class="parameter">0..9</replaceable></term>
d510 2
a511 2
      <term>-h <replaceable class="parameter">host</replaceable></term>
      <term>--host=<replaceable class="parameter">host</replaceable></term>
d523 2
a524 2
      <term>-p <replaceable class="parameter">port</replaceable></term>
      <term>--port=<replaceable class="parameter">port</replaceable></term>
d537 1
a537 1
      <term>-U <replaceable>username</replaceable></term>
d546 1
a546 1
      <term>-W</term>
@


1.41
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.40 2001/11/28 20:49:10 petere Exp $
d606 13
d620 1
a620 1
   <command>pg_dump</command> has a few limitations.
@


1.40
log
@proof-reading
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.39 2001/11/18 20:35:02 petere Exp $
Postgres documentation
d673 1
a673 1
   <application>Postgres95 release 0.02</application>.  The
d675 1
a675 1
   <application>PostgreSQL 7.1</application>.
@


1.39
log
@Initial round of tweakage for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.38 2001/10/23 22:11:22 tgl Exp $
d65 1
a65 1
   archive file.  The script files are in plain text format and
d70 2
a71 1
   products.  The alternative archive file formats are meant to be
d90 1
a90 1
   <productname>Postgres</productname> installation to another.
d149 1
a149 1
        This option is only meaningful for the plain text format.  For
d176 1
a176 1
        This option is only meaningful for the plain text format.  For
d195 1
a195 1
        This option is only meaningful for the plain text format.  For
d255 1
a255 1
           output a plain text <acronym>SQL</acronym> script file (default)
d264 1
a264 1
         output a <filename>tar</filename> archive suitable for input into 
d277 1
a277 1
         output a custom archive suitable for input into 
d364 1
a364 1
        This option is only meaningful for the plain text format.  For
d394 1
a394 1
        This option is only meaningful for the plain text format.  For
d460 1
a460 1
        Normally, if a (plain text mode) script generated by
d483 1
a483 1
        This option is only meaningful for the plain text format.  For
d515 1
a515 1
	<command>postmaster</command>
d528 1
a528 1
	extension on which the <command>postmaster</command>
@


1.38
log
@Editorial work on descriptions of options.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.37 2001/09/21 21:58:29 petere Exp $
d465 1
a465 1
        <option>-X use-set-session-authorization</option>, then
d467 1
a467 1
        linkend="sql-set-session-authorization"> commands.  This has
d475 1
a475 1
        Since <xref linkend="sql-set-session-authorization"> is a
@


1.37
log
@For consistency with the rest of PostgreSQL, rename BLOBs to large objects
in messages and documentation.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.36 2001/09/03 12:57:50 petere Exp $
d67 1
a67 1
   the state it was in at the time is was saved.  They can be used to
d94 2
a95 1
   <command>pg_restore</command>, it provides a flexible archival and
d99 8
a106 2
   database are to be restored.  See the <xref
   linkend="app-pgrestore"> documentation for details.
d134 1
a134 1
	Specifies the name of the database to be extracted.
d146 6
d170 8
a177 2
        Output commands to clean (drop) the schema prior to (the
        commands for) creating it.
d187 10
a196 1
	For plain text (script) output, include commands to create the database itself.
d206 1
a206 1
	Dump data as proper <command>INSERT</command> commands (rather
d224 2
a225 1
	...</literal>).  This will make restoration very slow.
d338 1
a338 1
	table.  Use this option if your application references the oid
d350 1
a350 1
	In plain text output mode, do not output commands to set the
d364 1
a364 1
        the other formats, you need to specify the option when you
d375 1
a375 1
	In plain text output mode, prohibit <command>pg_dump</command>
d394 1
a394 1
        the other formats, you need to specify the option when you
d483 1
a483 1
        the other formats, you need to specify the option when you
@


1.36
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.35 2001/08/22 20:23:23 petere Exp $
d147 1
a147 1
 	Dump data and <acronym>BLOB</acronym> data.
d619 2
a620 2
   To dump a database called mydb that contains
   <acronym>BLOB</acronym>s to a <filename>tar</filename> file:
d628 2
a629 2
   To reload this database (with <acronym>BLOB</acronym>s) to an
   existing database called newdb:
@


1.35
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
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.34 2001/08/12 19:02:39 petere Exp $
d23 1
a23 1
   Extract a <productname>Postgres</productname> database into a script file or other archive file 
@


1.34
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
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.33 2001/05/17 21:50:18 petere Exp $
d46 1
d63 13
a75 10
   <command>pg_dump</command> is a utility for dumping out a 
   <productname>Postgres</productname> database into a script or archive 
   file containing query commands. The script files are in text format 
   and can be used to reconstruct the database, even on other machines 
   and other architectures.
   The archive files, new with version 7.1, contain enough information for 
   <xref linkend="app-pgrestore"> 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
   also designed to be portable across architectures.
d79 5
a83 6
   <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 so
   that it can be readily copied in again, as well as imported into tools
   for editing.
d89 1
a89 4
   <productname>Postgres</productname> installation to another.  After running 
   <command>pg_dump</command>,
   one should examine the output for any warnings, especially
   in light of the limitations listed below. 
d93 20
a112 7
   When used with one of the alternate file formats and combined with 
   <command>pg_restore</command>, it provides a flexible archival 
   and transfer mechanism. <command>pg_dump</command> can be used 
   to backup an entire database, then <command>pg_restore</command> 
   can be used to examine the archive and/or select which parts of the 
   database are to be restored.
   See the <xref linkend="app-pgrestore"> documentation for details.
d157 1
a157 1
        Dump commands to clean (drop) the schema prior to (the
d178 4
a181 3
	Dump data as proper <command>INSERT</command> commands (not
	<command>COPY</command>). This will make restoration very
	slow.
d206 2
a207 1
	Send output to the specified file.
d217 2
a218 1
	Format can be one of the following:
d308 4
a311 1
	Dump object identifiers (<acronym>OID</acronym>s) for every table.
d321 16
a336 5
	In plain text output mode, do not set object ownership to
        match the original database. Typically,
        <command>pg_dump</command> issues
        (<command>psql</command>-specific) <command>\connect</command>
        statements to set ownership of schema elements.
d346 21
a366 2
	In plain text output mode, prohibit <command>pg_dump</command> 
        from issuing any <command>\connect</command> statements.
d386 4
a389 2
	Specify the superuser user name to use when disabling triggers and/or 
      setting ownership of schema elements.
d420 36
a455 2
	Prevent dumping of access privileges (grant/revoke commands)
	and table ownership information.
a529 1

d636 11
@


1.33
log
@Change "indices" to "indexes", per OED.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.32 2001/05/17 21:12:48 petere Exp $
d124 1
a124 1
	Dump only the data, not the schema (definitions).
d174 1
d179 4
a182 1
	column names.  This will make restoration very slow.
d327 1
a327 1
	Dump only the schema (definitions), no data.
d365 1
d369 2
a370 1
	Prevent dumping of ACLs (grant/revoke commands) and table ownership information.
a475 18
   <msgentry>
    <msg>
     <msgmain>
      <msgtext>
<screen><computeroutput>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
</computeroutput></screen>
      </msgtext>
     </msgmain>
    </msg>

    <msgexplan>
       <para>
	You do not have permission to read the database.
	Contact your <productname>Postgres</productname> site administrator.
       </para>
    </msgexplan>
   </msgentry>
a493 3
   The limitations mostly stem from
   difficulty in extracting certain meta-information from the system
   catalogs.
@


1.32
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
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.31 2001/03/17 16:27:31 petere Exp $
d77 1
a77 1
   user-defined types, functions, tables, indices, aggregates, and
@


1.31
log
@Tuning for docbook2man.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.30 2001/03/06 18:55:57 petere Exp $
d49 2
a50 1
   <arg>-u</arg>
d416 1
a416 1
      <term>-u</term>
d419 11
a429 4
	Use password authentication. 
	Prompts for
	<replaceable class="parameter">username</replaceable>
	and <replaceable class="parameter">password</replaceable>.
@


1.30
log
@Some editing, enhance markup, move description section before options list.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.28 2001/03/05 18:42:56 momjian Exp $
a37 1
   <sbr>
a46 1
   <sbr>
a49 1
   <sbr>
@


1.29
log
@- Minor correction to usage
@
text
@d8 1
a8 1
  <date>2000-12-25</date>
d12 2
a13 2
  <refentrytitle id="app-pgdump-title">
   <application>pg_dump</application>
d18 1
d20 2
a21 3
  <refname>
   <application>pg_dump</application>
  </refname>
d26 1
d28 79
a106 23
  <refsynopsisdivinfo>
   <date>2000-11-22</date>
  </refsynopsisdivinfo>
  <synopsis>
pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
    [ -p <replaceable class="parameter">port</replaceable> ]
    [ -t <replaceable class="parameter">table</replaceable> ]
    [ -a  ] [ -b ] [ -c  ] [-C] [ -d  ] [ -D  ] 
    [-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>] 
    [-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>] 
    [ -i  ] [ -n  ] [ -N  ] [ -o  ] [ -O ] [-R] 
    [ -s  ] [ -S ] [ -u  ] [ -v  ] [ -x ] [ -Z 0..9 ] 
    [ <replaceable class="parameter">dbname</replaceable> ]
  </synopsis>

  <refsect2 id="R2-APP-PG-DUMP-1">
   <refsect2info>
    <date>2000-11-22</date>
   </refsect2info>
   <title>
    Inputs
   </title>
d108 2
a109 2
    <application>pg_dump</application> accepts the following command
    line arguments:
a116 4
	<replaceable class="parameter">dbname</replaceable>
	defaults to the value of the
	<envar>USER</envar>
	environment variable.
d123 1
d126 1
a126 1
	Dump out only the data, no schema (definitions).
d133 1
d136 1
a136 1
 	Dump data and BLOB data.
d143 1
d146 2
a147 1
	Clean (drop) schema prior to create.
d154 1
d157 1
a157 1
	For plain text (script) output, include SQL to create the database itself.
d164 1
d167 3
a169 2
	Dump data as proper insert strings. This is not recommended for large databases
      for performance reasons.
d176 1
d179 2
a180 2
	Dump data as inserts with attribute names. This is not recommended for large databases
      for performance reasons.
d187 1
d197 1
a200 2
       </para>

d207 1
a207 1
         output a plain text SQL script file (default)
d216 2
a217 2
         output a TAR archive suitable for input into 
         <APPLICATION>pg_restore</APPLICATION>. Using this archive format 
d230 1
a230 1
         <APPLICATION>pg_restore</APPLICATION>. This is the most flexible 
d238 1
d245 1
d248 2
a249 2
        Ignore version mismatch between <application>pg_dump</application>
	and the database server.  Since <application>pg_dump</application>
d251 1
a251 1
	<application>pg_dump</application> is only intended to work with
d254 1
a254 1
	<application>pg_dump</application> then fails, don't
d262 1
d269 1
a269 1
	<application>pg_dump</application> prior to v6.4.
d276 1
d287 1
d297 1
d300 5
a304 4
	In plain text output mode, don't set object ownership to match the 
      original database. Typically, <APPLICATION>pg_dump</APPLICATION> 
      issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set 
      ownership of schema elements.
d311 1
d314 2
a315 2
	In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION> 
      from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.
d322 1
d325 1
a325 1
	Dump out only the schema (definitions), no data.
d332 1
d335 1
a335 1
	Specify the superuser username to use when disabling triggers and/or 
d343 1
a351 9
      <term>-u</term>
      <listitem>
       <para>
	Use password authentication. Prompts for username and password.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d353 1
d363 1
d373 1
d386 1
a386 1
    <application>pg_dump</application> also accepts 
d392 1
d395 2
a396 2
	Specifies the hostname of the machine on which the 
	<application>postmaster</application>
d398 1
a398 1
	as the directory for the unix domain socket.
d405 1
d409 1
a409 1
	extension on which the <application>postmaster</application>
d432 5
a436 10
  <refsect2 id="R2-APP-PG-DUMP-2">
   <refsect2info>
    <date>1998-11-05</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>pg_dump</application> will create a file or
    write to <filename>stdout</filename>.
d438 6
a443 3
    <variablelist>
     <varlistentry>
      <term><computeroutput>
d448 6
a453 2
       </computeroutput></term>
      <listitem>
d455 2
a456 2
	<application>pg_dump</application> could not attach to the 
	<application>postmaster</application> 
d458 1
a458 1
	ensure that the <application>postmaster</application> 
d460 1
a460 2
	port.  If your site uses an authentication system, ensure that you
	have obtained the required authentication credentials.
d462 2
a463 2
      </listitem>
     </varlistentry>
d465 10
a474 13
     <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>
d476 1
a476 5
     <varlistentry>
      <term><computeroutput>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
       </computeroutput></term>
      <listitem>
d481 3
a483 4
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
d487 1
a487 1
     <application>pg_dump</application> internally executes
d489 1
a489 1
     <application>pg_dump</application>,
d491 1
a491 1
     example, <application>psql</application>.
d494 1
a494 2
  </refsect2>
 </refsynopsisdiv>
a495 29
 <refsect1 id="R1-APP-PG-DUMP-1">
  <refsect1info>
   <date>2000-</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <application>pg_dump</application> is a utility for dumping out a 
   <productname>Postgres</productname> database into a script or archive 
   file containing query commands. The script files are in text format 
   and can be used to reconstruct the database, even on other machines 
   and other architectures.
  </para>
  <para> 
   The archive files, new with version 7.1, contain enough information for 
   <APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also
   allow pg_restore 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.
  </para>
  <para>
   <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 so
   that it can be readily copied in again, as well as imported into tools
   for editing.
  </para>
d497 2
d500 1
a500 32
   <application>pg_dump</application> 
   is useful for dumping out the contents of a database to move from one
   <productname>Postgres</productname> installation to another.  After running 
   <application>pg_dump</application>,
   one should examine the output for any warnings, especially
   in light of the limitations listed below. 
  </para>

  <para>
   When used with one of the alternate file formats and combined with 
   <APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival 
   and trasfer mechanism. <APPLICATION>pg_dump</APPLICATION> can be used 
   to backup an entire database, then <APPLICATION>pg_restore</APPLICATION> 
   can be used to examine the archive and/or select which parts of the 
   database are to be restored.
  </para>

  <para>
   See the <APPLICATION>pg_restore</APPLICATION> documentation for details.
  </para>

 </refsect1>

 <refsect1 id="R1-APP-PG-DUMP-2">
  <refsect1info>
   <date>2000-11-21</date>
  </refsect1info>
  <title>
   Notes
  </title>
  <para>
   <application>pg_dump</application> has a few limitations.
d508 1
a508 9
      <application>pg_dump</application> 
      does not understand partial indices. The reason is
      the same as above; partial index predicates are stored as plans.
     </para>
    </listitem>

    <listitem>
     <para>
      When dumping a single table or as plain text, <application>pg_dump</application> 
d510 1
a510 1
      entirity using one of the binary archive formats.
d516 1
a516 1
      When doing a data only dump, <application>pg_dump</application> emits queries
d527 3
a529 7
 <refsect1 id="R1-APP-PG-DUMP-3">
  <refsect1info>
   <date>2000-11-21</date>
  </refsect1info>
  <title>
   Usage
  </title>
d531 4
a534 5
   To dump a database of the same name as the user:

   <programlisting>
$ pg_dump > db.out
   </programlisting>
d539 3
a541 4

   <programlisting>
$ psql -e database < db.out
   </programlisting>
d545 2
a546 1
   To dump a database called mydb that contains BLOBs to a TAR file:
d548 3
a550 3
   <programlisting>
$ pg_dump -Ft --blobs mydb > db.tar
   </programlisting>
d554 2
a555 1
   To reload this database (with BLOBs) to an existing db called newdb:
d557 3
a559 3
   <programlisting>
$ pg_restore db.tar --dbname=newdb
   </programlisting>
d563 12
@


1.28
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
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.27 2000/12/25 23:15:26 petere Exp $
d568 1
a568 1
$ pg_restore db.tar --db=newdb
@


1.27
log
@Refine some things to create better looking man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.26 2000/11/30 23:20:50 tgl Exp $
d34 6
a39 6
    [ -t <replaceable class="parameter">table</replaceable> ]
    [ -a  ] [ -b ] [ -c  ] [-C] [ -d  ] [ -D  ] 
    [-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>] 
    [-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>] 
    [ -i  ] [ -n  ] [ -N  ] [ -o  ] [ -O ] [-R] 
    [ -s  ] [ -S ] [ -u  ] [ -v  ] [ -x ] [ -Z 0..9 ] 
d77 27
a103 27
     <varlistentry>
      <term>-b</term>
      <listitem>
       <para>
	Dump BLOB data.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-c</term>
      <listitem>
       <para>
	Clean (drop) schema prior to create.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-C</term>
      <listitem>
       <para>
	For plain text (script) output, include SQL to create the database itself.
       </para>
      </listitem>
     </varlistentry>

d108 1
a108 1
	Dump data as proper insert strings. This is not recommended for large databases
d118 1
a118 1
	Dump data as inserts with attribute names. This is not recommended for large databases
d123 57
a179 57

     <varlistentry>
      <term>-f <replaceable class="parameter">file</replaceable></term>
      <listitem>
       <para>
	Send output to the specified file.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-F <replaceable class="parameter">format</replaceable></term>
      <listitem>
       <para>
	Format can be one of the following:
       </para>


       <variablelist>
        <varlistentry>
         <term>p</term>
         <listitem>
          <para>
         output a plain text SQL script file (default)
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>t</term>
         <listitem>
          <para>
         output a TAR archive suitable for input into 
         <APPLICATION>pg_restore</APPLICATION>. 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>
         output a custom archive suitable for input into 
         <APPLICATION>pg_restore</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.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>

      </listitem>
     </varlistentry>
d220 31
a250 31
     <varlistentry>
      <term>-o</term>
      <listitem>
       <para>
	Dump object identifiers (<acronym>OID</acronym>s) for every table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-O</term>
      <listitem>
       <para>
	In plain text output mode, don't set object ownership to match the 
      original database. Typically, <APPLICATION>pg_dump</APPLICATION> 
      issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set 
      ownership of schema elements.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-R</term>
      <listitem>
       <para>
	In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION> 
      from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.
       </para>
      </listitem>
     </varlistentry>

d260 19
a278 19
     <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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-t <replaceable class="parameter">table</replaceable></term>
      <listitem>
       <para>
	Dump data for <replaceable class="parameter">table</replaceable> only.
       </para>
      </listitem>
     </varlistentry>

d305 11
a315 11

     <varlistentry>
      <term>-Z <replaceable class="parameter">0..9</replaceable></term>
      <listitem>
       <para>
	Specify the compression level to use in archive formats that support 
      compression (currently only the custom archive format supports compression).
       </para>
      </listitem>
     </varlistentry>

d445 5
a449 5
   <productname>Postgres</productname> database into a script or archive 
   file containing query commands. The script files are in text format 
   and can be used to reconstruct the database, even on other machines 
   and other architectures.
  </para>
d451 7
a457 7
   The archive files, new with version 7.1, contain enough information for 
   <APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also
   allow pg_restore 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.
  </para>
  <para>
d474 14
a487 14

  <para>
   When used with one of the alternate file formats and combined with 
   <APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival 
   and trasfer mechanism. <APPLICATION>pg_dump</APPLICATION> can be used 
   to backup an entire database, then <APPLICATION>pg_restore</APPLICATION> 
   can be used to examine the archive and/or select which parts of the 
   database are to be restored.
  </para>

  <para>
   See the <APPLICATION>pg_restore</APPLICATION> documentation for details.
  </para>

d514 3
a516 3
      When dumping a single table or as plain text, <application>pg_dump</application> 
      does not handle large objects. Large objects must be dumped in their
      entirity using one of the binary archive formats.
d555 17
a571 17

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

   <programlisting>
$ pg_dump -Ft --blobs mydb > 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>

@


1.26
log
@Repair residual sillinesses from UUNET virtual host/socket path patch.
I hope all the dust has settled out now ...
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.25 2000/11/22 01:41:13 momjian Exp $
d7 4
d15 1
d451 1
a451 1
   The archive files, new with this v7.1, contain enough information for 
@


1.25
log
@Make socket option specify just the directory, not the full path.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.24 2000/11/21 15:39:09 pjw Exp $
d374 3
a376 2
connectDB() failed: Is the postmaster running and accepting connections
            at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
@


1.24
log
@Update for new pg_dump with blobs etc
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.23 2000/11/13 23:57:20 momjian Exp $
d326 1
a326 1
	as the path to a unix domain socket.
@


1.23
log
@Add mention of hostname leading slash handling to all manual pages that use -h.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.22 2000/11/13 23:37:51 momjian Exp $
d18 1
a18 1
   Extract a <productname>Postgres</productname> database into a script file
d23 1
a23 1
   <date>1999-07-20</date>
d29 6
a34 3
    [ -t <replaceable class="parameter">table</replaceable> ]
    [ -a ] [ -c ] [ -d ] [ -D ] [ -i ] [ -n ] [ -N ]
    [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
d40 1
a40 1
    <date>1998-11-05</date>
d72 27
a98 9
     <varlistentry>
      <term>-c</term>
      <listitem>
       <para>
	Clean (drop) schema prior to create.
       </para>
      </listitem>
     </varlistentry>

d103 2
a104 1
	Dump data as proper insert strings.
d113 2
a114 1
	Dump data as inserts with attribute names
d118 57
d215 31
a245 9
     <varlistentry>
      <term>-o</term>
      <listitem>
       <para>
	Dump object identifiers (<acronym>OID</acronym>s) for every table.
       </para>
      </listitem>
     </varlistentry>

d255 19
a273 9
     <varlistentry>
      <term>-t <replaceable class="parameter">table</replaceable></term>
      <listitem>
       <para>
	Dump data for <replaceable class="parameter">table</replaceable> only.
       </para>
      </listitem>
     </varlistentry>

d300 11
d432 1
a432 1
   <date>1998-11-05</date>
d439 13
a451 4
   <productname>Postgres</productname> database into a script file
   containing query commands.  The script
   files are in text format and can be used to reconstruct the database,
   even on other machines and other architectures.  
d465 1
a465 1
   one should examine the output script file for any warnings, especially
d468 14
d486 1
a486 1
   <date>1998-11-05</date>
d508 3
a510 2
      <application>pg_dump</application> does not handle large objects.
      Large objects are ignored and must be dealt with manually. 
d529 1
a529 1
   <date>1998-11-05</date>
d549 17
@


1.22
log
@Remove -k unix socketpath option from client side, allow hostname with
leading slash to behave as a unix socket path.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.21 2000/11/13 15:18:08 momjian Exp $
d202 2
a203 2
	is running.  Defaults to using a local Unix domain socket
	rather than an IP connection.
@


1.21
log
@UUNET is looking into offering PostgreSQL as a part of a managed web
hosting product, on both shared and dedicated machines.  We currently
offer Oracle and MySQL, and it would be a nice middle-ground.
However, as shipped, PostgreSQL lacks the following features we need
that MySQL has:

1. The ability to listen only on a particular IP address.  Each
   hosting customer has their own IP address, on which all of their
   servers (http, ftp, real media, etc.) run.
2. The ability to place the Unix-domain socket in a mode 700 directory.
   This allows us to automatically create an empty database, with an
   empty DBA password, for new or upgrading customers without having
   to interactively set a DBA password and communicate it to (or from)
   the customer.  This in turn cuts down our install and upgrade times.
3. The ability to connect to the Unix-domain socket from within a
   change-rooted environment.  We run CGI programs chrooted to the
   user's home directory, which is another reason why we need to be
   able to specify where the Unix-domain socket is, instead of /tmp.
4. The ability to, if run as root, open a pid file in /var/run as
   root, and then setuid to the desired user.  (mysqld -u can almost
   do this; I had to patch it, too).

The patch below fixes problem 1-3.  I plan to address #4, also, but
haven't done so yet.  These diffs are big enough that they should give
the PG development team something to think about in the meantime :-)
Also, I'm about to leave for 2 weeks' vacation, so I thought I'd get
out what I have, which works (for the problems it tackles), now.

With these changes, we can set up and run PostgreSQL with scripts the
same way we can with apache or proftpd or mysql.

In summary, this patch makes the following enhancements:

1. Adds an environment variable PGUNIXSOCKET, analogous to MYSQL_UNIX_PORT,
   and command line options -k --unix-socket to the relevant programs.
2. Adds a -h option to postmaster to set the hostname or IP address to
   listen on instead of the default INADDR_ANY.
3. Extends some library interfaces to support the above.
4. Fixes a few memory leaks in PQconnectdb().

The default behavior is unchanged from stock 7.0.2; if you don't use
any of these new features, they don't change the operation.

David J. MacKenzie
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.20 2000/10/05 19:48:18 momjian Exp $
a27 1
    [ -k <replaceable class="parameter">path</replaceable> ]
a203 15
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-k <replaceable class="parameter">path</replaceable></term>
      <listitem>
       <para>
	Specifies the local Unix domain socket file path
	on which the <application>postmaster</application>
	is listening for connections.
        Without this option, the socket path name defaults to
        the value of the <envar>PGUNIXSOCKET</envar> environment
	variable (if set), otherwise it is constructed
        from the port number.
@


1.20
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.19 2000/07/22 04:45:09 momjian Exp $
d27 3
a29 1
pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
d205 15
@


1.19
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.18 2000/07/21 00:24:37 momjian Exp $
d72 1
a72 1
	Clean(drop) schema prior to create.
d174 1
a174 1
	Specifies verbose mode
d202 1
a202 1
	rather than an IP connection..
@


1.18
log
@Change prompt % to $.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.17 2000/04/11 14:43:54 momjian Exp $
d370 1
a370 1
      reenable them after the data has been inserted.  If the restore is stopped
@


1.17
log
@    Attached  is  are  diffs  for  CREATE/ALTER  table  doc  I've
    forgotten in my mailbox (sorry). Haven't tried to  apply  and
    since I don't have working sgml stuff cannot check.

Jan
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.16 2000/04/04 05:22:45 tgl Exp $
d390 1
a390 1
% pg_dump > db.out
d398 1
a398 1
% psql -e database < db.out
@


1.16
log
@Add a check to pg_dump to see whether backend is same version as pg_dump.
If not, abort by default.  Abort can be prevented by using -i or
--ignore-version switch.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.15 2000/03/27 17:14:43 thomas Exp $
d365 10
@


1.15
log
@Start updating for the v7.0 release.
Use "generic functions" for math and other routines.
Use SQL92 "type 'literal'" syntax rather than Postgres "'literal'::type".
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.14 2000/01/24 19:34:13 petere Exp $
d29 1
a29 1
    [ -a ] [ -c ] [ -d ] [ -D ] [ -n ] [ -N ]
d91 16
@


1.14
log
@Made abstime/reltime use int4 instead of time_t (TODO item)
Made type equivalency apply to aggregates (TODO item)
Fixed parsing bug in psql
Reverted some stupid options changes I made to pg_dump
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.13 2000/01/18 00:03:34 petere Exp $
d102 2
a103 1
	This was the default behavior in pre-v6.4 <application>pg_dump</application>.
@


1.13
log
@Updated user interfaces on initdb, initlocation, pg_dump, ipcclean to a GNU-compliant'ish state.
Made ipcclean work on Linux.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.12 1999/07/22 15:09:13 thomas Exp $
d30 1
a30 1
    [ -O ] [ -s ] [ -u ] [ -v ] [ -x ]
d118 1
a118 1
      <term>-O</term>
@


1.12
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d28 1
a28 1
    [ -t <replaceable class="parameter">table</replaceable> ] [ -f <replaceable class="parameter">outputfile</replaceable> ]
d30 1
a30 1
    [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
a95 9
      <term>-f <replaceable class="parameter">filename</replaceable></term>
      <listitem>
       <para>
	Specifies the output file. Defaults to <filename>stdout</filename>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
d118 1
a118 1
      <term>-o</term>
@


1.11
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 6
a6 1
<refentry id="APP-PG-DUMP">
d8 1
a8 1
  <refentrytitle id="pg-dump">
d23 1
a23 1
   <date>1998-11-05</date>
@


1.10
log
@Minor updates for release.
Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml
 (the emacs parser) to handle parsing.
@
text
@d1 20
a20 20
<REFENTRY ID="APP-PG-DUMP">
<REFMETA>
<REFENTRYTITLE id="pg-dump">
<application>pg_dump</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>pg_dump</application>
</REFNAME>
<REFPURPOSE>
Extract a <productname>Postgres</productname> database into a script file
</REFPURPOSE>
  </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-11-05</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
d23 1
a23 2
    [ -t <replaceable class="parameter">table</replaceable> ]
    [ -f <replaceable class="parameter">outputfile</replaceable> ]
d27 1
a27 1
</SYNOPSIS>
d29 251
a279 327
    <REFSECT2 ID="R2-APP-PG-DUMP-1">
      <REFSECT2INFO>
	<DATE>1998-11-05</DATE>
      </REFSECT2INFO>
      <TITLE>
	Inputs
      </TITLE>
      <PARA>
	<application>pg_dump</application> accepts the following command line arguments:
	
	<variablelist>
	  <varlistentry>
	    <term>
	      <replaceable class="parameter">dbname</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the name of the database to be extracted.
		<replaceable class="parameter">dbname</replaceable>
		defaults to the value of the
		<envar>USER</envar>
		environment variable.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -a
	    </term>
	    <listitem>
	      <para>
		Dump out only the data, no schema (definitions).
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -c
	    </term>
	    <listitem>
	      <para>
		Clean(drop) schema prior to create.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -d
	    </term>
	    <listitem>
	      <para>
		Dump data as proper insert strings.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -D
	    </term>
	    <listitem>
	      <para>
		Dump data as inserts with attribute names
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -f <replaceable class="parameter">filename</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the output file. Defaults to <filename>stdout</filename>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -n
	    </term>
	    <listitem>
	      <para>
		Suppress double quotes around identifiers unless absolutely necessary.
		This may cause trouble loading this dumped data if there are reserved words
		used for identifiers. 
		This was the default behavior in pre-v6.4 <application>pg_dump</application>.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -N
	    </term>
	    <listitem>
	      <para>
		Include double quotes around identifiers.
		This is the default.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -o
	    </term>
	    <listitem>
	      <para>
		Dump object identifiers (<acronym>OID</acronym>s) for every table.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -s
	    </term>
	    <listitem>
	      <para>
		Dump out only the schema (definitions), no data.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -t <replaceable class="parameter">table</replaceable>
	    </term>
	    <listitem>
	      <para>
		Dump data for <replaceable class="parameter">table</replaceable> only.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -u
	    </term>
	    <listitem>
	      <para>
		Use password authentication. Prompts for username and password.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -v
	    </term>
	    <listitem>
	      <para>
		Specifies verbose mode
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -x
	    </term>
	    <listitem>
	      <para>
		Prevent dumping of ACLs (grant/revoke commands) and table ownership information.
	      </para>
	    </listitem>
	  </varlistentry>

	</variablelist>
      </para>
      <para>
	<application>pg_dump</application> also accepts 
	the following command line arguments for connection parameters:
	
	<variablelist>
	  <varlistentry>
	    <term>
	      -h <replaceable class="parameter">host</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the hostname of the machine on which the 
		<application>postmaster</application>
		is running.  Defaults to using a local Unix domain socket
		rather than an IP connection..
	      </para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      -p <replaceable class="parameter">port</replaceable>
	    </term>
	    <listitem>
	      <para>
		Specifies the Internet TCP/IP port or local Unix domain socket file 
		extension on which the <application>postmaster</application>
		is listening for connections.  The port number defaults to 5432,
		or the value of the <envar>PGPORT</envar>
		environment variable (if set).
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>
	      -u
	    </term>
	    <listitem>
	      <para>
		Use password authentication. 
		Prompts for
		<replaceable class="parameter">username</replaceable>
		and <replaceable class="parameter">password</replaceable>.
	      </para>
	    </listitem>
	  </varlistentry>

	</variablelist>
      </para>
    </refsect2>

    <REFSECT2 ID="R2-APP-PG-DUMP-2">
      <REFSECT2INFO>
	<DATE>1998-11-05</DATE>
      </REFSECT2INFO>
      <TITLE>
	Outputs
      </TITLE>
      <PARA>
	<application>pg_dump</application> will create a file or
	write to <filename>stdout</filename>.

	<variablelist>
	  <varlistentry>
	    <term>
	      Connection to database 'template1' failed.
	      connectDB() failed: Is the postmaster running and accepting connections
	      at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
	    </term>
	    <listitem>
	      <para>
		<application>pg_dump</application> could not attach to the 
		<application>postmaster</application> 
		process on the specified host and port.  If you see this message,
		ensure that the <application>postmaster</application> 
		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>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>
	      Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
	      FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
	    </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>
	  
	  <varlistentry>
	    <term>
	      dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
	    </term>
	    <listitem>
	      <para>
		You do not have permission to read the database.
		Contact your <productname>Postgres</productname> site administrator.
	      </para>
	    </listitem>
	  </varlistentry>
	  
	</variablelist>
      </para>
      <note>
	<para>
	  <application>pg_dump</application> internally executes
	  <command>SELECT</command> statements. If you have problems running
	  <application>pg_dump</application>,
	  make sure you are able to select information from the database using, for
	  example, <application>psql</application>.
	</para>
      </note>
    </refsect2>
  </refsynopsisdiv>
      
  <REFSECT1 ID="R1-APP-PG-DUMP-1">
    <REFSECT1INFO>
      <DATE>1998-11-05</DATE>
    </REFSECT1INFO>
    <TITLE>
      Description
    </TITLE>
    <PARA>
      <application>pg_dump</application> is a utility for dumping out a 
      <productname>Postgres</productname> database into a script file
      containing query commands.  The script
      files are in text format and can be used to reconstruct the database,
      even on other machines and other 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 so
      that it can be readily copied in again, as well as imported into tools
      for editing.
    </para>
    <para>
      <application>pg_dump</application> 
      is useful for dumping out the contents of a database to move from one
      <productname>Postgres</productname> installation to another.  After running 
      <application>pg_dump</application>,
      one should examine the output script file for any warnings, especially
      in light of the limitations listed below. 
    </para>
  </refsect1>
d281 1
a281 57
  <REFSECT1 ID="R1-APP-PG-DUMP-2">
    <REFSECT1INFO>
      <DATE>1998-11-05</DATE>
    </REFSECT1INFO>
    <TITLE>
      Notes
    </TITLE>
    <PARA>
      <application>pg_dump</application> has a few limitations.
      The limitations mostly stem from
      difficulty in extracting certain meta-information from the system
      catalogs.

      <variablelist>
	<varlistentry>
	  <term>
	    partial indices
	  </term>
	  <listitem>
	    <para>
	      <application>pg_dump</application> 
	      does not understand partial indices. The reason is
	      the same as above; partial index predicates are stored as plans.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    large objects
	  </term>
	  <listitem>
	    <para>
	      <application>pg_dump</application> does not handle large objects.
	      Large objects are ignored and must be dealt with manually. 
	    </para>
	  </listitem>
	</varlistentry>
	
      </variablelist>
    </para>
  </refsect1>

  <REFSECT1 ID="R1-APP-PG-DUMP-3">
    <REFSECT1INFO>
      <DATE>1998-11-05</DATE>
    </REFSECT1INFO>
    <TITLE>
      Usage
    </TITLE>
    <PARA>
      To dump a database of the same name as the user:

      <programlisting>
	% pg_dump > db.out
      </programlisting>
    </para>
d283 5
a287 5
      To reload this database:
      
      <programlisting>
	psql -e database < db.out
      </programlisting>
d289 108
a396 2
  </refsect1>
</REFENTRY>
@


1.9
log
@Make pg_dump dump ACL's by default, print warning on use of -z, and add
new -x option to skip acl dump.
@
text
@d25 2
a26 1
    [ -a ] [ -c ] [ -d ] [ -D ] [ -n ] [ -N ] [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
@


1.8
log
@Here is a new version of my patch for allowing pg_dump to DROP schema
elements prior to CREATEing new ones.  It is under control of the -c
command line option (with the default being status quo).

The DROP TRIGGER portion still needs implementation.  Anyone able to
help clarify what exactly the CREATE TRIGGER portion does so I can fix
this?

Again, I have tried this with tables/indexes/sequences, but do not
have other schema elements in my database.  As a result, I am not 100%
convinced that I got the syntax correct in all cases (but think I did,
nonetheless).  If anyone can check the other cases, I'd appreciate it.

Cheers,
Brook

[I added manual page and sgml additions for the new -c option.]
@
text
@d25 1
a25 1
    [ -a ] [ -c ] [ -d ] [ -D ] [ -n ] [ -N ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
d193 1
a193 1
	      -z
d197 1
a197 1
		Include ACLs (grant/revoke commands) and table ownership information.
@


1.7
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d25 1
a25 1
    [ -a ] [ -d ] [ -D ] [ -n ] [ -N ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
d62 11
@


1.6
log
@Add new "-N" flag to force double quotes around identifiers.
Fix missing mention of "-n" flag in synopsis.
@
text
@d15 1
d29 382
a410 304
<REFSECT2 ID="R2-APP-PG-DUMP-1">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dump</application> accepts the following command line arguments:

<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be extracted.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.

<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).

<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.

<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names

<varlistentry>
<term>
-f <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para>
Specifies the output file. Defaults to <filename>stdout</filename>.

<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers. 
This was the default behavior in pre-v6.4 <application>pg_dump</application>.

<varlistentry>
<term>
-N
</term>
<listitem>
<para>
Include double quotes around identifiers.
This is the default.

<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.

<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.

<varlistentry>
<term>
-t <replaceable class="parameter">table</replaceable>
</term>
<listitem>
<para>
Dump data for <replaceable class="parameter">table</replaceable> only.

<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.

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

<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.

</variablelist>

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

<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the 
<application>postmaster</application>
is running.  Defaults to using a local Unix domain socket
 rather than an IP connection..

<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file 
extension on which the <application>postmaster</application>
is listening for connections.  The port number defaults to 5432,
 or the value of the <envar>PGPORT</envar>
environment variable (if set).

<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. 
Prompts for
<replaceable class="parameter">username</replaceable>
 and <replaceable class="parameter">password</replaceable>.

</variablelist>

<REFSECT2 ID="R2-APP-PG-DUMP-2">
<REFSECT2INFO>
<DATE>1998-11-05</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dump</application> will create a file or
 write to <filename>stdout</filename>.

<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
 at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>pg_dump</application> could not attach to the 
<application>postmaster</application> 
process on the specified host and port.  If you see this message,
ensure that the <application>postmaster</application> 
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.

<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<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.

<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.

</variablelist>

<note>
<para>
<application>pg_dump</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dump</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</note>

<REFSECT1 ID="R1-APP-PG-DUMP-1">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dump</application> is a utility for dumping out a 
<productname>Postgres</productname> database into a script file
 containing query commands.  The script
files are in text format and can be used to reconstruct the database,
even on other machines and other 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 so
that it can be readily copied in again, as well as imported into tools
for editing.

<para>
<application>pg_dump</application> 
is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another.  After running 
<application>pg_dump</application>,
 one should examine the output script file for any warnings, especially
in light of the limitations listed below. 

<REFSECT1 ID="R1-APP-PG-DUMP-2">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<application>pg_dump</application> has a few limitations.
The limitations mostly stem from
difficulty in extracting certain meta-information from the system
catalogs.

<variablelist>
<varlistentry>
<term>
partial indices
<listitem>
<para>
<application>pg_dump</application> 
does not understand partial indices. The reason is
the same as above; partial index predicates are stored as plans.

<varlistentry>
<term>
large objects
<listitem>
<para>
<application>pg_dump</application> does not handle large objects.
Large objects are ignored and must be dealt with manually. 

</variablelist>

<REFSECT1 ID="R1-APP-PG-DUMP-3">
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump a database of the same name as the user:

<programlisting>
% pg_dump > db.out
</programlisting>

<para>
To reload this database:

<programlisting>
psql -e database < db.out
</programlisting>

@


1.5
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d17 1
a17 1
<DATE>1998-10-04</DATE>
d24 1
a24 1
    [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
d30 1
a30 1
<DATE>1998-10-04</DATE>
d91 11
a101 1
used for identifiers.
d196 1
a196 1
<DATE>1998-10-04</DATE>
d252 1
a252 1
<DATE>1998-10-04</DATE>
d280 1
a280 1
<DATE>1998-10-04</DATE>
d313 1
a313 1
<DATE>1998-10-04</DATE>
@


1.4
log
@Add new "-n" flag to pg_dump.
Update UNLISTEN to not require double-quotes around the wildcard argument.
Clean up markup.
@
text
@d3 1
a3 1
<REFENTRYTITLE>
d9 1
a9 1
<REFNAME id="pg-dump">
@


1.3
log
@Update pg_dump sgml and manuals to remove rule restriction.
@
text
@d281 1
@


1.2
log
@> > There is a bug in check_foreign_key of refint.c which is bundled with
> > the standard distribution. It occurs when a trigger calling this
> > function recursively fires another trigger which calls the same
> > function. The calling check_foreign_key loses its plan informantion and
> > when it tries to use it the backend closes its channel. You can check it
> > with the sql script I am attaching below.
> > The solution to this is to do a find_plan again before executing it at
> > line 483 of refint.c.
> > Therefore two more lines should be added before line 483:

Anand Surelia
@
text
@a280 11
<variablelist>
<varlistentry>
<term>
rules
<listitem>
<para>
<application>pg_dump</application> 
does not understand user-defined rules and
will fail to dump them properly.  (This is due to the fact that
rules are stored as plans in the catalogs and not textually.)

@


1.1
log
@Add new information for utility commands.
 Haven't yet done cleardbdir, ipcclean, pg_passwd, and pg_upgrade.
Add reference info for the SQL VACUUM command (oops, forgot it earlier).
@
text
@d284 1
a284 1
rules and views
d288 1
a288 1
does not understand user-defined rules and views and
d290 1
a290 1
rules are stored as plans in the catalogs and not textually).
@
