head	1.250;
access;
symbols
	REL9_0_0:1.244.2.2
	REL9_1_ALPHA1:1.250
	REL9_0_RC1:1.244.2.2
	REL9_0_BETA4:1.244.2.1
	REL9_0_STABLE:1.244.0.2
	REL9_0_BETA3:1.244
	REL9_0_BETA2:1.244
	REL7_4_29:1.99.2.2
	REL8_0_25:1.130.4.6
	REL8_1_21:1.154.2.4
	REL8_2_17:1.175.2.8
	REL8_3_11:1.198.2.3
	REL8_4_4:1.225.2.4
	REL9_0_BETA1:1.244
	REL9_0_ALPHA5_BRANCH:1.243.0.2
	REL9_0_ALPHA5:1.243
	REL7_4_28:1.99.2.2
	REL8_0_24:1.130.4.6
	REL8_1_20:1.154.2.4
	REL8_2_16:1.175.2.8
	REL8_3_10:1.198.2.3
	REL8_4_3:1.225.2.4
	REL9_0_ALPHA4:1.239
	REL9_0_ALPHA4_BRANCH:1.239.0.2
	REL8_5_ALPHA3:1.235
	REL8_5_ALPHA3_BRANCH:1.235.0.2
	REL7_4_27:1.99.2.1
	REL8_0_23:1.130.4.5
	REL8_1_19:1.154.2.3
	REL8_2_15:1.175.2.7
	REL8_3_9:1.198.2.2
	REL8_4_2:1.225.2.3
	REL8_5_ALPHA2:1.232
	REL8_5_ALPHA2_BRANCH:1.232.0.2
	REL7_4_26:1.99.2.1
	REL8_0_22:1.130.4.5
	REL8_1_18:1.154.2.3
	REL8_2_14:1.175.2.7
	REL8_3_8:1.198.2.2
	REL8_4_1:1.225.2.3
	REL8_5_ALPHA1:1.229
	REL8_5_ALPHA1_BRANCH:1.229.0.2
	REL8_4_STABLE:1.225.0.2
	REL8_4_0:1.225
	REL8_4_RC2:1.225
	REL8_4_RC1:1.225
	REL8_4_BETA2:1.225
	REL8_4_BETA1:1.223
	REL7_4_25:1.99
	REL8_0_21:1.130.4.3
	REL8_1_17:1.154.2.1
	REL8_2_13:1.175.2.5
	REL8_3_7:1.198
	REL7_4_24:1.99
	REL8_0_20:1.130.4.3
	REL8_1_16:1.154.2.1
	REL8_2_12:1.175.2.5
	REL8_3_6:1.198
	REL7_4_23:1.99
	REL8_0_19:1.130.4.3
	REL8_1_15:1.154.2.1
	REL8_2_11:1.175.2.5
	REL8_3_5:1.198
	REL7_4_22:1.99
	REL8_0_18:1.130.4.3
	REL8_1_14:1.154.2.1
	REL8_2_10:1.175.2.5
	REL8_3_4:1.198
	REL7_4_21:1.99
	REL8_0_17:1.130.4.3
	REL8_1_13:1.154.2.1
	REL8_2_9:1.175.2.5
	REL8_3_3:1.198
	REL7_4_20:1.99
	REL8_0_16:1.130.4.3
	REL8_1_12:1.154.2.1
	REL8_2_8:1.175.2.5
	REL8_3_2:1.198
	REL8_2_7:1.175.2.5
	REL8_3_1:1.198
	REL8_3_STABLE:1.198.0.2
	REL8_3_0:1.198
	REL8_3_RC2:1.198
	REL7_3_21:1.79
	REL7_4_19:1.99
	REL8_0_15:1.130.4.3
	REL8_1_11:1.154.2.1
	REL8_2_6:1.175.2.5
	REL8_3_RC1:1.198
	REL8_3_BETA4:1.196
	REL8_3_BETA3:1.196
	REL8_3_BETA2:1.195
	REL8_3_BETA1:1.195
	REL7_3_20:1.79
	REL7_4_18:1.99
	REL8_0_14:1.130.4.3
	REL8_1_10:1.154.2.1
	REL8_2_5:1.175.2.5
	REL7_3_19:1.79
	REL7_4_17:1.99
	REL8_0_13:1.130.4.3
	REL8_1_9:1.154.2.1
	REL8_2_4:1.175.2.5
	REL8_0_12:1.130.4.3
	REL8_1_8:1.154.2.1
	REL8_2_3:1.175.2.3
	REL7_3_18:1.79
	REL7_4_16:1.99
	REL8_0_11:1.130.4.3
	REL8_1_7:1.154.2.1
	REL8_2_2:1.175.2.3
	REL8_0_10:1.130.4.3
	REL8_1_6:1.154.2.1
	REL8_2_1:1.175.2.3
	REL7_4_15:1.99
	REL7_3_17:1.79
	REL8_2_STABLE:1.175.0.2
	REL8_2_0:1.175
	REL8_2_RC1:1.175
	REL8_2_BETA3:1.174
	REL8_2_BETA2:1.172
	REL8_1_5:1.154.2.1
	REL8_0_9:1.130.4.3
	REL7_4_14:1.99
	REL7_3_16:1.79
	REL8_2_BETA1:1.169
	REL7_3_15:1.79
	REL7_4_13:1.99
	REL8_0_8:1.130.4.3
	REL8_1_4:1.154.2.1
	REL7_3_14:1.79
	REL7_4_12:1.99
	REL8_0_7:1.130.4.3
	REL8_1_3:1.154.2.1
	REL7_3_13:1.79
	REL7_4_11:1.99
	REL8_0_6:1.130.4.3
	REL8_1_2:1.154.2.1
	REL7_3_12:1.79
	REL7_4_10:1.99
	REL8_0_5:1.130.4.3
	REL8_1_1:1.154.2.1
	REL8_1_STABLE:1.154.0.2
	REL8_1_0:1.154
	REL8_1_0RC1:1.152
	REL8_1_0BETA4:1.150
	REL8_1_0BETA3:1.150
	REL7_3_11:1.79
	REL7_4_9:1.99
	REL8_0_4:1.130.4.3
	REL8_1_0BETA2:1.149
	REL8_1_0BETA1:1.149
	REL7_2_8:1.61
	REL7_3_10:1.79
	REL7_4_8:1.99
	REL8_0_3:1.130.4.3
	REL8_0_2:1.130.4.3
	REL7_2_7:1.61
	REL7_3_9:1.79
	REL7_4_7:1.99
	REL8_0_1:1.130.4.2
	REL8_0_STABLE:1.130.0.4
	REL8_0_0:1.130.0.2
	REL8_0_0RC5:1.129
	REL8_0_0RC4:1.129
	REL8_0_0RC3:1.126
	REL8_0_0RC2:1.124
	REL8_0_0RC1:1.123
	REL8_0_0BETA5:1.123
	REL8_0_0BETA4:1.123
	REL7_4_6:1.99
	REL7_3_8:1.79
	REL7_2_6:1.61
	REL8_0_0BETA3:1.122
	REL8_0_0BETA2:1.121
	REL7_2_5:1.61
	REL7_4_5:1.99
	REL7_3_7:1.79
	REL7_4_4:1.99
	REL8_0_0BETA1:1.119
	REL7_4_3:1.99
	REL7_4_2:1.99
	REL7_3_6:1.79
	REL7_4_1:1.99
	REL7_3_5:1.79
	REL7_4:1.99
	REL7_4_RC2:1.99
	REL7_4_STABLE:1.99.0.2
	REL7_4_RC1:1.99
	REL7_4_BETA5:1.98
	REL7_4_BETA4:1.97
	REL7_4_BETA3:1.97
	REL7_4_BETA2:1.94
	WIN32_DEV:1.94.0.2
	REL7_4_BETA1:1.94
	REL7_3_4:1.79
	REL7_3_2:1.79
	REL7_2_4:1.61
	REL7_3_STABLE:1.79.0.2
	REL7_2_3:1.61
	REL7_2_STABLE:1.61.0.2
	REL7_2:1.61
	REL7_2_RC2:1.61
	REL7_2_RC1:1.61
	REL7_2_BETA5:1.61
	REL7_2_BETA4:1.61
	REL7_2_BETA3:1.60
	REL7_2_BETA2:1.60
	REL7_2_BETA1:1.60
	REL7_1_2:1.47
	REL7_1_STABLE:1.47.0.2
	REL7_1_BETA:1.44
	REL7_1_BETA3:1.45
	REL7_1_BETA2:1.45
	REL7_1:1.47
	REL7_0_PATCHES:1.33.0.2
	REL7_0:1.31
	REL6_5_PATCHES:1.9.0.2
	REL6_5:1.9
	REL6_4:1.4.0.2;
locks; strict;
comment	@# @;


1.250
date	2010.08.17.04.37.21;	author petere;	state Exp;
branches;
next	1.249;

1.249
date	2010.08.14.13.59.49;	author tgl;	state Exp;
branches;
next	1.248;

1.248
date	2010.08.12.00.40.59;	author tgl;	state Exp;
branches;
next	1.247;

1.247
date	2010.08.03.18.33.09;	author tgl;	state Exp;
branches;
next	1.246;

1.246
date	2010.07.20.03.54.19;	author rhaas;	state Exp;
branches;
next	1.245;

1.245
date	2010.07.10.00.50.24;	author rhaas;	state Exp;
branches;
next	1.244;

1.244
date	2010.04.03.07.23.02;	author petere;	state Exp;
branches
	1.244.2.1;
next	1.243;

1.243
date	2010.03.21.00.43.40;	author momjian;	state Exp;
branches;
next	1.242;

1.242
date	2010.03.08.12.38.37;	author mha;	state Exp;
branches;
next	1.241;

1.241
date	2010.03.07.17.02.33;	author mha;	state Exp;
branches;
next	1.240;

1.240
date	2010.03.06.15.28.09;	author mha;	state Exp;
branches;
next	1.239;

1.239
date	2010.02.19.14.36.45;	author momjian;	state Exp;
branches;
next	1.238;

1.238
date	2010.02.19.03.50.03;	author momjian;	state Exp;
branches;
next	1.237;

1.237
date	2010.01.29.17.44.12;	author rhaas;	state Exp;
branches;
next	1.236;

1.236
date	2009.12.24.23.36.39;	author tgl;	state Exp;
branches;
next	1.235;

1.235
date	2009.11.25.20.26.30;	author tgl;	state Exp;
branches;
next	1.234;

1.234
date	2009.11.22.22.06.30;	author tgl;	state Exp;
branches;
next	1.233;

1.233
date	2009.11.22.05.20.41;	author tgl;	state Exp;
branches;
next	1.232;

1.232
date	2009.10.13.21.04.01;	author tgl;	state Exp;
branches;
next	1.231;

1.231
date	2009.10.08.16.34.00;	author alvherre;	state Exp;
branches;
next	1.230;

1.230
date	2009.10.05.19.24.34;	author tgl;	state Exp;
branches;
next	1.229;

1.229
date	2009.08.11.12.02.58;	author momjian;	state Exp;
branches;
next	1.228;

1.228
date	2009.08.10.02.39.04;	author adunstan;	state Exp;
branches;
next	1.227;

1.227
date	2009.07.25.17.04.19;	author tgl;	state Exp;
branches;
next	1.226;

1.226
date	2009.07.24.19.35.44;	author petere;	state Exp;
branches;
next	1.225;

1.225
date	2009.04.21.17.23.05;	author momjian;	state Exp;
branches
	1.225.2.1;
next	1.224;

1.224
date	2009.04.21.15.49.06;	author momjian;	state Exp;
branches;
next	1.223;

1.223
date	2009.04.08.22.29.30;	author tgl;	state Exp;
branches;
next	1.222;

1.222
date	2009.04.04.00.39.14;	author tgl;	state Exp;
branches;
next	1.221;

1.221
date	2009.04.02.15.15.31;	author momjian;	state Exp;
branches;
next	1.220;

1.220
date	2009.02.26.16.02.37;	author petere;	state Exp;
branches;
next	1.219;

1.219
date	2009.02.09.14.09.56;	author momjian;	state Exp;
branches;
next	1.218;

1.218
date	2009.01.20.02.38.37;	author momjian;	state Exp;
branches;
next	1.217;

1.217
date	2009.01.09.19.27.14;	author tgl;	state Exp;
branches;
next	1.216;

1.216
date	2009.01.07.04.51.34;	author momjian;	state Exp;
branches;
next	1.215;

1.215
date	2009.01.06.23.01.57;	author momjian;	state Exp;
branches;
next	1.214;

1.214
date	2008.12.19.16.25.16;	author petere;	state Exp;
branches;
next	1.213;

1.213
date	2008.12.01.09.20.37;	author petere;	state Exp;
branches;
next	1.212;

1.212
date	2008.11.06.15.18.35;	author tgl;	state Exp;
branches;
next	1.211;

1.211
date	2008.09.06.20.18.08;	author tgl;	state Exp;
branches;
next	1.210;

1.210
date	2008.09.06.00.01.21;	author tgl;	state Exp;
branches;
next	1.209;

1.209
date	2008.07.03.03.37.16;	author tgl;	state Exp;
branches;
next	1.208;

1.208
date	2008.06.11.10.48.16;	author heikki;	state Exp;
branches;
next	1.207;

1.207
date	2008.06.01.16.23.08;	author tgl;	state Exp;
branches;
next	1.206;

1.206
date	2008.05.16.17.17.00;	author momjian;	state Exp;
branches;
next	1.205;

1.205
date	2008.05.16.16.59.05;	author momjian;	state Exp;
branches;
next	1.204;

1.204
date	2008.05.14.04.07.01;	author momjian;	state Exp;
branches;
next	1.203;

1.203
date	2008.05.08.17.04.26;	author momjian;	state Exp;
branches;
next	1.202;

1.202
date	2008.05.08.00.27.57;	author momjian;	state Exp;
branches;
next	1.201;

1.201
date	2008.05.05.01.38.08;	author adunstan;	state Exp;
branches;
next	1.200;

1.200
date	2008.05.02.22.50.21;	author tgl;	state Exp;
branches;
next	1.199;

1.199
date	2008.03.30.18.10.20;	author tgl;	state Exp;
branches;
next	1.198;

1.198
date	2007.12.11.19.57.32;	author tgl;	state Exp;
branches
	1.198.2.1;
next	1.197;

1.197
date	2007.12.11.19.01.06;	author tgl;	state Exp;
branches;
next	1.196;

1.196
date	2007.10.29.17.29.59;	author momjian;	state Exp;
branches;
next	1.195;

1.195
date	2007.09.14.14.31.22;	author momjian;	state Exp;
branches;
next	1.194;

1.194
date	2007.08.22.04.45.20;	author tgl;	state Exp;
branches;
next	1.193;

1.193
date	2007.07.10.00.21.31;	author tgl;	state Exp;
branches;
next	1.192;

1.192
date	2007.06.28.06.40.16;	author neilc;	state Exp;
branches;
next	1.191;

1.191
date	2007.05.03.15.47.48;	author alvherre;	state Exp;
branches;
next	1.190;

1.190
date	2007.03.26.17.23.37;	author tgl;	state Exp;
branches;
next	1.189;

1.189
date	2007.03.16.08.28.01;	author mha;	state Exp;
branches;
next	1.188;

1.188
date	2007.03.03.17.19.11;	author momjian;	state Exp;
branches;
next	1.187;

1.187
date	2007.02.23.18.20.58;	author momjian;	state Exp;
branches;
next	1.186;

1.186
date	2007.02.21.23.22.42;	author momjian;	state Exp;
branches;
next	1.185;

1.185
date	2007.02.21.23.21.12;	author momjian;	state Exp;
branches;
next	1.184;

1.184
date	2007.02.20.18.10.58;	author momjian;	state Exp;
branches;
next	1.183;

1.183
date	2007.02.01.19.10.24;	author momjian;	state Exp;
branches;
next	1.182;

1.182
date	2007.02.01.00.28.19;	author momjian;	state Exp;
branches;
next	1.181;

1.181
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.180;

1.180
date	2007.01.20.16.57.31;	author neilc;	state Exp;
branches;
next	1.179;

1.179
date	2006.12.19.01.53.36;	author adunstan;	state Exp;
branches;
next	1.178;

1.178
date	2006.12.06.15.47.22;	author momjian;	state Exp;
branches;
next	1.177;

1.177
date	2006.12.06.15.40.11;	author momjian;	state Exp;
branches;
next	1.176;

1.176
date	2006.12.05.17.40.55;	author momjian;	state Exp;
branches;
next	1.175;

1.175
date	2006.11.21.17.01.58;	author momjian;	state Exp;
branches
	1.175.2.1;
next	1.174;

1.174
date	2006.10.31.02.29.15;	author tgl;	state Exp;
branches;
next	1.173;

1.173
date	2006.10.31.01.52.31;	author neilc;	state Exp;
branches;
next	1.172;

1.172
date	2006.10.23.18.10.32;	author petere;	state Exp;
branches;
next	1.171;

1.171
date	2006.10.09.23.31.29;	author tgl;	state Exp;
branches;
next	1.170;

1.170
date	2006.10.03.21.14.46;	author momjian;	state Exp;
branches;
next	1.169;

1.169
date	2006.09.16.00.30.19;	author momjian;	state Exp;
branches;
next	1.168;

1.168
date	2006.08.30.23.34.21;	author tgl;	state Exp;
branches;
next	1.167;

1.167
date	2006.08.29.22.25.04;	author tgl;	state Exp;
branches;
next	1.166;

1.166
date	2006.07.27.19.52.04;	author tgl;	state Exp;
branches;
next	1.165;

1.165
date	2006.05.31.22.34.35;	author tgl;	state Exp;
branches;
next	1.164;

1.164
date	2006.05.31.11.47.20;	author momjian;	state Exp;
branches;
next	1.163;

1.163
date	2006.05.31.11.35.17;	author momjian;	state Exp;
branches;
next	1.162;

1.162
date	2006.05.26.19.51.29;	author tgl;	state Exp;
branches;
next	1.161;

1.161
date	2006.04.02.20.08.20;	author neilc;	state Exp;
branches;
next	1.160;

1.160
date	2006.02.13.21.29.08;	author tgl;	state Exp;
branches;
next	1.159;

1.159
date	2006.02.12.04.04.32;	author momjian;	state Exp;
branches;
next	1.158;

1.158
date	2006.02.12.02.54.30;	author momjian;	state Exp;
branches;
next	1.157;

1.157
date	2005.12.20.00.51.45;	author tgl;	state Exp;
branches;
next	1.156;

1.156
date	2005.12.18.02.17.16;	author petere;	state Exp;
branches;
next	1.155;

1.155
date	2005.12.09.19.19.17;	author momjian;	state Exp;
branches;
next	1.154;

1.154
date	2005.11.04.23.14.02;	author petere;	state Exp;
branches
	1.154.2.1;
next	1.153;

1.153
date	2005.11.01.21.09.50;	author tgl;	state Exp;
branches;
next	1.152;

1.152
date	2005.10.30.03.01.49;	author momjian;	state Exp;
branches;
next	1.151;

1.151
date	2005.10.28.02.39.07;	author momjian;	state Exp;
branches;
next	1.150;

1.150
date	2005.10.04.19.01.14;	author petere;	state Exp;
branches;
next	1.149;

1.149
date	2005.08.14.18.49.29;	author tgl;	state Exp;
branches;
next	1.148;

1.148
date	2005.07.18.20.57.52;	author momjian;	state Exp;
branches;
next	1.147;

1.147
date	2005.07.14.08.42.36;	author momjian;	state Exp;
branches;
next	1.146;

1.146
date	2005.07.10.03.46.12;	author momjian;	state Exp;
branches;
next	1.145;

1.145
date	2005.06.14.02.57.38;	author momjian;	state Exp;
branches;
next	1.144;

1.144
date	2005.06.13.06.36.22;	author neilc;	state Exp;
branches;
next	1.143;

1.143
date	2005.06.13.02.40.08;	author neilc;	state Exp;
branches;
next	1.142;

1.142
date	2005.06.10.16.31.48;	author momjian;	state Exp;
branches;
next	1.141;

1.141
date	2005.06.10.16.26.59;	author neilc;	state Exp;
branches;
next	1.140;

1.140
date	2005.06.10.15.34.25;	author momjian;	state Exp;
branches;
next	1.139;

1.139
date	2005.06.09.15.27.26;	author momjian;	state Exp;
branches;
next	1.138;

1.138
date	2005.06.02.01.23.48;	author momjian;	state Exp;
branches;
next	1.137;

1.137
date	2005.05.30.15.24.23;	author momjian;	state Exp;
branches;
next	1.136;

1.136
date	2005.05.29.03.32.18;	author momjian;	state Exp;
branches;
next	1.135;

1.135
date	2005.04.28.13.09.59;	author momjian;	state Exp;
branches;
next	1.134;

1.134
date	2005.03.14.06.19.01;	author tgl;	state Exp;
branches;
next	1.133;

1.133
date	2005.02.11.04.19.05;	author momjian;	state Exp;
branches;
next	1.132;

1.132
date	2005.01.22.23.22.19;	author momjian;	state Exp;
branches;
next	1.131;

1.131
date	2005.01.22.22.31.52;	author momjian;	state Exp;
branches;
next	1.130;

1.130
date	2005.01.14.00.24.23;	author momjian;	state Exp;
branches
	1.130.4.1;
next	1.129;

1.129
date	2005.01.06.21.20.44;	author tgl;	state Exp;
branches;
next	1.128;

1.128
date	2005.01.06.18.29.08;	author tgl;	state Exp;
branches;
next	1.127;

1.127
date	2005.01.04.03.58.16;	author tgl;	state Exp;
branches;
next	1.126;

1.126
date	2004.12.28.23.17.38;	author tgl;	state Exp;
branches;
next	1.125;

1.125
date	2004.12.27.20.13.48;	author tgl;	state Exp;
branches;
next	1.124;

1.124
date	2004.12.13.18.05.10;	author petere;	state Exp;
branches;
next	1.123;

1.123
date	2004.10.06.18.39.15;	author momjian;	state Exp;
branches;
next	1.122;

1.122
date	2004.09.20.18.51.17;	author tgl;	state Exp;
branches;
next	1.121;

1.121
date	2004.08.24.00.06.51;	author neilc;	state Exp;
branches;
next	1.120;

1.120
date	2004.08.14.23.49.07;	author tgl;	state Exp;
branches;
next	1.119;

1.119
date	2004.07.15.03.56.04;	author momjian;	state Exp;
branches;
next	1.118;

1.118
date	2004.07.13.16.48.15;	author momjian;	state Exp;
branches;
next	1.117;

1.117
date	2004.07.12.20.41.08;	author momjian;	state Exp;
branches;
next	1.116;

1.116
date	2004.06.18.06.13.05;	author tgl;	state Exp;
branches;
next	1.115;

1.115
date	2004.04.22.17.38.14;	author neilc;	state Exp;
branches;
next	1.114;

1.114
date	2004.04.22.14.33.38;	author momjian;	state Exp;
branches;
next	1.113;

1.113
date	2004.04.22.01.53.17;	author momjian;	state Exp;
branches;
next	1.112;

1.112
date	2004.04.21.00.34.18;	author momjian;	state Exp;
branches;
next	1.111;

1.111
date	2004.04.19.17.22.30;	author momjian;	state Exp;
branches;
next	1.110;

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

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

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

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

1.106
date	2004.02.13.05.10.02;	author momjian;	state Exp;
branches;
next	1.105;

1.105
date	2004.02.12.19.58.16;	author momjian;	state Exp;
branches;
next	1.104;

1.104
date	2004.01.20.23.48.56;	author tgl;	state Exp;
branches;
next	1.103;

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

1.102
date	2003.12.23.23.13.14;	author momjian;	state Exp;
branches;
next	1.101;

1.101
date	2003.12.01.22.21.54;	author momjian;	state Exp;
branches;
next	1.100;

1.100
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.99;

1.99
date	2003.11.01.01.56.29;	author petere;	state Exp;
branches
	1.99.2.1;
next	1.98;

1.98
date	2003.10.04.01.04.46;	author petere;	state Exp;
branches;
next	1.97;

1.97
date	2003.09.12.02.40.09;	author momjian;	state Exp;
branches;
next	1.96;

1.96
date	2003.09.03.22.05.08;	author petere;	state Exp;
branches;
next	1.95;

1.95
date	2003.08.31.17.32.24;	author petere;	state Exp;
branches;
next	1.94;

1.94
date	2003.08.02.02.44.38;	author momjian;	state Exp;
branches
	1.94.2.1;
next	1.93;

1.93
date	2003.07.28.00.14.42;	author tgl;	state Exp;
branches;
next	1.92;

1.92
date	2003.07.27.03.32.26;	author momjian;	state Exp;
branches;
next	1.91;

1.91
date	2003.07.23.15.05.42;	author tgl;	state Exp;
branches;
next	1.90;

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

1.89
date	2003.05.14.03.26.00;	author tgl;	state Exp;
branches;
next	1.88;

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

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

1.86
date	2003.03.24.14.32.51;	author petere;	state Exp;
branches;
next	1.85;

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

1.84
date	2003.01.07.20.56.06;	author tgl;	state Exp;
branches;
next	1.83;

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

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

1.81
date	2002.12.12.21.02.19;	author momjian;	state Exp;
branches;
next	1.80;

1.80
date	2002.11.08.19.12.21;	author momjian;	state Exp;
branches;
next	1.79;

1.79
date	2002.10.19.00.22.14;	author tgl;	state Exp;
branches;
next	1.78;

1.78
date	2002.10.11.23.03.48;	author petere;	state Exp;
branches;
next	1.77;

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

1.76
date	2002.09.21.18.32.54;	author petere;	state Exp;
branches;
next	1.75;

1.75
date	2002.09.18.20.09.32;	author petere;	state Exp;
branches;
next	1.74;

1.74
date	2002.08.27.20.16.48;	author petere;	state Exp;
branches;
next	1.73;

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

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

1.71
date	2002.08.10.19.35.00;	author tgl;	state Exp;
branches;
next	1.70;

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

1.69
date	2002.07.28.15.22.21;	author petere;	state Exp;
branches;
next	1.68;

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

1.67
date	2002.06.20.16.00.43;	author momjian;	state Exp;
branches;
next	1.66;

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

1.65
date	2002.03.20.19.43.30;	author tgl;	state Exp;
branches;
next	1.64;

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

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

1.62
date	2002.03.05.00.00.58;	author momjian;	state Exp;
branches;
next	1.61;

1.61
date	2001.12.08.03.24.38;	author thomas;	state Exp;
branches;
next	1.60;

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

1.59
date	2001.09.11.05.11.59;	author ishii;	state Exp;
branches;
next	1.58;

1.58
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.57;

1.57
date	2001.07.15.13.45.03;	author petere;	state Exp;
branches;
next	1.56;

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

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

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

1.53
date	2001.05.17.21.50.18;	author petere;	state Exp;
branches;
next	1.52;

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

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

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

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

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

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

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

1.45
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.44;

1.44
date	2000.11.22.01.41.13;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2000.11.13.23.57.20;	author momjian;	state Exp;
branches;
next	1.42;

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

1.41
date	2000.11.13.15.18.08;	author momjian;	state Exp;
branches;
next	1.40;

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

1.39
date	2000.10.12.22.16.58;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.37;

1.37
date	2000.09.27.11.56.16;	author momjian;	state Exp;
branches;
next	1.36;

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

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

1.34
date	2000.07.21.17.58.49;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2000.05.12.00.54.52;	author momjian;	state Exp;
branches;
next	1.32;

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

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

1.30
date	2000.03.27.17.14.43;	author thomas;	state Exp;
branches;
next	1.29;

1.29
date	2000.03.21.01.52.12;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	2000.03.11.13.56.23;	author petere;	state Exp;
branches;
next	1.27;

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

1.26
date	2000.02.20.14.29.21;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2000.02.13.21.45.13;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2000.02.10.20.08.55;	author petere;	state Exp;
branches;
next	1.23;

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

1.22
date	2000.01.29.16.58.27;	author petere;	state Exp;
branches;
next	1.21;

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

1.20
date	2000.01.14.22.18.01;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2000.01.12.19.36.34;	author petere;	state Exp;
branches;
next	1.18;

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

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

1.16
date	99.11.05.15.44.56;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	99.11.05.00.57.39;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	99.11.04.22.07.56;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	99.10.26.04.40.56;	author momjian;	state Exp;
branches;
next	1.12;

1.12
date	99.10.14.01.28.41;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	99.07.30.00.59.50;	author momjian;	state Exp;
branches;
next	1.10;

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

1.9
date	99.07.06.17.16.41;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.06.14.07.37.04;	author thomas;	state Exp;
branches;
next	1.7;

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

1.6
date	99.04.13.09.46.58;	author ishii;	state Exp;
branches;
next	1.5;

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

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

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

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

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

1.94.2.1
date	2003.09.07.04.36.46;	author momjian;	state Exp;
branches;
next	1.94.2.2;

1.94.2.2
date	2003.09.12.02.46.00;	author momjian;	state Exp;
branches;
next	;

1.99.2.1
date	2009.08.10.02.39.09;	author adunstan;	state Exp;
branches;
next	1.99.2.2;

1.99.2.2
date	2010.03.08.12.38.54;	author mha;	state Exp;
branches;
next	;

1.130.4.1
date	2005.01.22.23.05.53;	author momjian;	state Exp;
branches;
next	1.130.4.2;

1.130.4.2
date	2005.01.22.23.23.53;	author momjian;	state Exp;
branches;
next	1.130.4.3;

1.130.4.3
date	2005.02.11.04.19.18;	author momjian;	state Exp;
branches;
next	1.130.4.4;

1.130.4.4
date	2009.08.10.02.39.12;	author adunstan;	state Exp;
branches;
next	1.130.4.5;

1.130.4.5
date	2009.08.15.20.22.50;	author momjian;	state Exp;
branches;
next	1.130.4.6;

1.130.4.6
date	2010.03.08.12.39.10;	author mha;	state Exp;
branches;
next	;

1.154.2.1
date	2005.12.09.19.19.28;	author momjian;	state Exp;
branches;
next	1.154.2.2;

1.154.2.2
date	2009.08.10.02.39.16;	author adunstan;	state Exp;
branches;
next	1.154.2.3;

1.154.2.3
date	2009.08.15.20.22.59;	author momjian;	state Exp;
branches;
next	1.154.2.4;

1.154.2.4
date	2010.03.08.12.39.29;	author mha;	state Exp;
branches;
next	;

1.175.2.1
date	2006.12.05.17.41.02;	author momjian;	state Exp;
branches;
next	1.175.2.2;

1.175.2.2
date	2006.12.06.15.40.32;	author momjian;	state Exp;
branches;
next	1.175.2.3;

1.175.2.3
date	2006.12.11.22.48.08;	author momjian;	state Exp;
branches;
next	1.175.2.4;

1.175.2.4
date	2007.02.20.18.11.17;	author momjian;	state Exp;
branches;
next	1.175.2.5;

1.175.2.5
date	2007.03.26.17.23.45;	author tgl;	state Exp;
branches;
next	1.175.2.6;

1.175.2.6
date	2009.08.10.02.39.20;	author adunstan;	state Exp;
branches;
next	1.175.2.7;

1.175.2.7
date	2009.08.15.20.23.09;	author momjian;	state Exp;
branches;
next	1.175.2.8;

1.175.2.8
date	2010.03.08.12.39.37;	author mha;	state Exp;
branches;
next	;

1.198.2.1
date	2009.08.10.02.39.24;	author adunstan;	state Exp;
branches;
next	1.198.2.2;

1.198.2.2
date	2009.08.15.20.23.20;	author momjian;	state Exp;
branches;
next	1.198.2.3;

1.198.2.3
date	2010.03.08.12.39.42;	author mha;	state Exp;
branches;
next	;

1.225.2.1
date	2009.07.24.19.35.26;	author petere;	state Exp;
branches;
next	1.225.2.2;

1.225.2.2
date	2009.08.10.02.50.18;	author adunstan;	state Exp;
branches;
next	1.225.2.3;

1.225.2.3
date	2009.08.15.19.33.29;	author momjian;	state Exp;
branches;
next	1.225.2.4;

1.225.2.4
date	2010.03.08.12.39.51;	author mha;	state Exp;
branches;
next	1.225.2.5;

1.225.2.5
date	2010.08.17.04.49.33;	author petere;	state Exp;
branches;
next	;

1.244.2.1
date	2010.07.10.00.50.37;	author rhaas;	state Exp;
branches;
next	1.244.2.2;

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


desc
@@


1.250
log
@Spell and markup checking
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.249 2010/08/14 13:59:49 tgl Exp $
PostgreSQL documentation
-->

<refentry id="APP-PSQL">
  <refmeta>
    <refentrytitle><application>psql</application></refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Application</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>psql</application></refname>
    <refpurpose>
      <productname>PostgreSQL</productname> interactive terminal
    </refpurpose>
  </refnamediv>

 <indexterm zone="app-psql">
  <primary>psql</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>psql</command>
   <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
   <arg><replaceable class="parameter">dbname</replaceable>
   <arg><replaceable class="parameter">username</replaceable></arg></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

    <para>
     <application>psql</application> is a terminal-based front-end to
     <productname>PostgreSQL</productname>. It enables you to type in
     queries interactively, issue them to
     <productname>PostgreSQL</productname>, and see the query results.
     Alternatively, input can be from a file. In addition, it provides a
     number of meta-commands and various shell-like features to
     facilitate writing scripts and automating a wide variety of tasks.
    </para>
 </refsect1>

 <refsect1 id="R1-APP-PSQL-3">
  <title>Options</title>

  <variablelist>
    <varlistentry>
      <term><option>-a</></term>
      <term><option>--echo-all</></term>
      <listitem>
      <para>
      Print all input lines to standard output as they are read. This is more
      useful for script processing than interactive mode. This is
      equivalent to setting the variable <varname>ECHO</varname> to
      <literal>all</literal>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-A</></term>
      <term><option>--no-align</></term>
      <listitem>
      <para>
      Switches to unaligned output mode. (The default output mode is
      otherwise aligned.)
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-c <replaceable class="parameter">command</replaceable></></term>
      <term><option>--command <replaceable class="parameter">command</replaceable></></term>
      <listitem>
      <para>
      Specifies that <application>psql</application> is to execute one
      command string, <replaceable class="parameter">command</replaceable>,
      and then exit. This is useful in shell scripts. Start-up files
      (<filename>psqlrc</filename> and <filename>~/.psqlrc</filename>) are
      ignored with this option.
      </para>
      <para>
      <replaceable class="parameter">command</replaceable> must be either
      a command string that is completely parsable by the server (i.e.,
      it contains no <application>psql</application>-specific features),
      or a single backslash command. Thus you cannot mix
      <acronym>SQL</acronym> and <application>psql</application>
      meta-commands with this option. To achieve that, you could
      pipe the string into <application>psql</application>, like
      this: <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
      (<literal>\\</> is the separator meta-command.)
      </para>
      <para>
       If the command string contains multiple SQL commands, they are
       processed in a single transaction, unless there are explicit
       <command>BEGIN</>/<command>COMMIT</> commands included in the
       string to divide it into multiple transactions.  This is
       different from the behavior when the same string is fed to
       <application>psql</application>'s standard input.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-d <replaceable class="parameter">dbname</replaceable></></term>
      <term><option>--dbname <replaceable class="parameter">dbname</replaceable></></term>
      <listitem>
      <para>
       Specifies the name of the database to connect to. This is
       equivalent to specifying <replaceable
       class="parameter">dbname</replaceable> as the first non-option
       argument on the command line.
      </para>
      <para>
       If this parameter contains an <symbol>=</symbol> sign, it is treated as a
       <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-e</></term>
      <term><option>--echo-queries</></term>
      <listitem>
      <para>
      Copy all SQL commands sent to the server to standard output as well.
      This is equivalent
      to setting the variable <varname>ECHO</varname> to
      <literal>queries</literal>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-E</></term>
      <term><option>--echo-hidden</></term>
      <listitem>
      <para>
      Echo the actual queries generated by <command>\d</command> and other backslash
      commands. You can use this to study <application>psql</application>'s
      internal operations. This is equivalent to
      setting the variable <varname>ECHO_HIDDEN</varname> from within
      <application>psql</application>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-f <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--file <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
      Use the file <replaceable class="parameter">filename</replaceable>
      as the source of commands instead of reading commands interactively.
      After the file is processed, <application>psql</application>
      terminates. This is in many ways equivalent to the internal
      command <command>\i</command>.
      </para>

      <para>
       If <replaceable>filename</replaceable> is <literal>-</literal>
       (hyphen), then standard input is read.
      </para>

      <para>
      Using this option is subtly different from writing <literal>psql
      &lt; <replaceable
      class="parameter">filename</replaceable></literal>. In general,
      both will do what you expect, but using <literal>-f</literal>
      enables some nice features such as error messages with line
      numbers. There is also a slight chance that using this option will
      reduce the start-up overhead. On the other hand, the variant using
      the shell's input redirection is (in theory) guaranteed to yield
      exactly the same output you would have received had you entered
      everything by hand.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-F <replaceable class="parameter">separator</replaceable></></term>
      <term><option>--field-separator <replaceable class="parameter">separator</replaceable></></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      field separator for unaligned output. This is equivalent to
      <command>\pset fieldsep</command> or <command>\f</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-h <replaceable class="parameter">hostname</replaceable></></term>
      <term><option>--host <replaceable class="parameter">hostname</replaceable></></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.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-H</></term>
      <term><option>--html</></term>
      <listitem>
      <para>
      Turn on <acronym>HTML</acronym> tabular output. This is
      equivalent to <literal>\pset format html</literal> or the
      <command>\H</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-l</></term>
      <term><option>--list</></term>
      <listitem>
      <para>
      List all available databases, then exit. Other non-connection
      options are ignored. This is similar to the internal command
      <command>\list</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-L <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--log-file <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
       Write all query output into file <replaceable
       class="parameter">filename</replaceable>, in addition to the
       normal output destination.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-o <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--output <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
      Put all query output into file <replaceable
      class="parameter">filename</replaceable>. This is equivalent to
      the command <command>\o</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></></term>
      <term><option>--port <replaceable class="parameter">port</replaceable></></term>
      <listitem>
      <para>
      Specifies the TCP port or the local Unix-domain
      socket file extension on which the server is listening for
      connections. Defaults to the value of the <envar>PGPORT</envar>
      environment variable or, if not set, to the port specified at
      compile time, usually 5432.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-P <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--pset <replaceable class="parameter">assignment</replaceable></></term>
      <listitem>
      <para>
      Specifies printing options, in the style of
      <command>\pset</command>. Note that here you
      have to separate name and value with an equal sign instead of a
      space. For example, to set the output format to LaTeX, you could write
      <literal>-P format=latex</literal>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-q</></term>
      <term><option>--quiet</></term>
      <listitem>
      <para>
      Specifies that <application>psql</application> should do its work
      quietly. By default, it prints welcome messages and various
      informational output. If this option is used, none of this
      happens. This is useful with the <option>-c</option> option.
      Within <application>psql</application> you can also set the
      <varname>QUIET</varname> variable to achieve the same effect.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-R <replaceable class="parameter">separator</replaceable></></term>
      <term><option>--record-separator <replaceable class="parameter">separator</replaceable></></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      record separator for unaligned output. This is equivalent to the
      <command>\pset recordsep</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-s</></term>
      <term><option>--single-step</></term>
      <listitem>
      <para>
      Run in single-step mode. That means the user is prompted before
      each command is sent to the server, with the option to cancel
      execution as well. Use this to debug scripts.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-S</></term>
      <term><option>--single-line</></term>
      <listitem>
      <para>
      Runs in single-line mode where a newline terminates an SQL command, as a
      semicolon does.
      </para>

      <note>
      <para>
      This mode is provided for those who insist on it, but you are not
      necessarily encouraged to use it. In particular, if you mix
      <acronym>SQL</acronym> and meta-commands on a line the order of
      execution might not always be clear to the inexperienced user.
      </para>
      </note>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-t</></term>
      <term><option>--tuples-only</></term>
      <listitem>
      <para>
      Turn off printing of column names and result row count footers,
      etc. This is equivalent to the <command>\t</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-T <replaceable class="parameter">table_options</replaceable></></term>
      <term><option>--table-attr <replaceable class="parameter">table_options</replaceable></></term>
      <listitem>
      <para>
      Specifies options to be placed within the
      <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
      <command>\pset</command> for details.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-U <replaceable class="parameter">username</replaceable></></term>
      <term><option>--username <replaceable class="parameter">username</replaceable></></term>
      <listitem>
      <para>
      Connect to the database as the user <replaceable
      class="parameter">username</replaceable> instead of the default.
      (You must have permission to do so, of course.)
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-v <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--set <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
      <listitem>
      <para>
      Perform a variable assignment, like the <command>\set</command>
      internal command. Note that you must separate name and value, if
      any, by an equal sign on the command line. To unset a variable,
      leave off the equal sign. To just set a variable without a value,
      use the equal sign but leave off the value. These assignments are
      done during a very early stage of start-up, so variables reserved
      for internal purposes might get overwritten later.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-V</></term>
      <term><option>--version</></term>
      <listitem>
      <para>
      Print the <application>psql</application> version and exit.
      </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>

      <para>
       Note that this option will remain set for the entire session,
       and so it affects uses of the meta-command
       <command>\connect</command> as well as the initial connection attempt.
      </para>
     </listitem>
    </varlistentry>

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

      <para>
       This option is never essential, since <application>psql</application>
       will automatically prompt for a password if the server demands
       password authentication.  However, <application>psql</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>

      <para>
       Note that this option will remain set for the entire session,
       and so it affects uses of the meta-command
       <command>\connect</command> as well as the initial connection attempt.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-x</></term>
      <term><option>--expanded</></term>
      <listitem>
      <para>
      Turn on the expanded table formatting mode. This is equivalent to the
      <command>\x</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-X,</></term>
      <term><option>--no-psqlrc</></term>
      <listitem>
      <para>
      Do not read the start-up file (neither the system-wide
      <filename>psqlrc</filename> file nor the user's
      <filename>~/.psqlrc</filename> file).
      </para>
      </listitem>
    </varlistentry>

     <varlistentry>
      <term><option>-1</option></term>
      <term><option>--single-transaction</option></term>
      <listitem>
       <para>
        When <application>psql</application> executes a script with the
        <option>-f</> option, adding this option wraps
        <command>BEGIN</>/<command>COMMIT</> around the script to execute it
        as a single transaction.  This ensures that either all the commands
        complete successfully, or no changes are applied.
       </para>

       <para>
        If the script itself uses <command>BEGIN</>, <command>COMMIT</>,
        or <command>ROLLBACK</>, this option will not have the desired
        effects.
        Also, if the script contains any command that cannot be executed
        inside a transaction block, specifying this option will cause that
        command (and hence the whole transaction) to fail.
       </para>
      </listitem>
     </varlistentry>

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

  </variablelist>
 </refsect1>


 <refsect1>
  <title>Exit Status</title>

  <para>
   <application>psql</application> returns 0 to the shell if it
   finished normally, 1 if a fatal error of its own occurs (e.g. out of memory,
   file not found), 2 if the connection to the server went bad
   and the session was not interactive, and 3 if an error occurred in a
   script and the variable <varname>ON_ERROR_STOP</varname> was set.
  </para>
 </refsect1>


 <refsect1>
  <title>Usage</title>

  <refsect2 id="R2-APP-PSQL-connecting">
    <title>Connecting To A Database</title>

    <para>
    <application>psql</application> is a regular
    <productname>PostgreSQL</productname> client application. In order
    to connect to a database you need to know the name of your target
    database, the host name and port number of the server, and what user
    name you want to connect as. <application>psql</application> can be
    told about those parameters via command line options, namely
    <option>-d</option>, <option>-h</option>, <option>-p</option>, and
    <option>-U</option> respectively. If an argument is found that does
    not belong to any option it will be interpreted as the database name
    (or the user name, if the database name is already given). Not all
    of these options are required; there are useful defaults. If you omit the host
    name, <application>psql</> will connect via a Unix-domain socket
    to a server on the local host, or via TCP/IP to <literal>localhost</> on
    machines that don't have Unix-domain sockets. The default port number is
    determined at compile time.
    Since the database server uses the same default, you will not have
    to specify the port in most cases. The default user name is your
    Unix user name, as is the default database name. Note that you cannot
    just connect to any database under any user name. Your database
    administrator should have informed you about your access rights.
    </para>

    <para>
    When the defaults aren't quite right, you can save yourself
    some typing by setting the environment variables
    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
    <envar>PGPORT</envar> and/or <envar>PGUSER</envar> to appropriate
    values. (For additional environment variables, see <xref
    linkend="libpq-envars">.) It is also convenient to have a
    <filename>~/.pgpass</> file to avoid regularly having to type in
    passwords. See <xref linkend="libpq-pgpass"> for more information.
    </para>

    <para>
     An alternative way to specify connection parameters is in a
     <parameter>conninfo</parameter> string, which is used instead of a
     database name. This mechanism give you very wide control over the
     connection. For example:
<programlisting>
$ <userinput>psql "service=myservice sslmode=require"</userinput>
</programlisting>
     This way you can also use LDAP for connection parameter lookup as
     described in <xref linkend="libpq-ldap">.
     See <xref linkend="libpq-connect"> for more information on all the
     available connection options.
    </para>

    <para>
    If the connection could not be made for any reason (e.g., insufficient
    privileges, server is not running on the targeted host, etc.),
    <application>psql</application> will return an error and terminate.
    </para>
  </refsect2>

  <refsect2 id="R2-APP-PSQL-4">
    <title>Entering SQL Commands</title>

    <para>
    In normal operation, <application>psql</application> provides a
    prompt with the name of the database to which
    <application>psql</application> is currently connected, followed by
    the string <literal>=&gt;</literal>. For example:
<programlisting>
$ <userinput>psql testdb</userinput>
psql (&version;)
Type "help" for help.

testdb=&gt;
</programlisting>
    </para>

    <para>
    At the prompt, the user can type in <acronym>SQL</acronym> commands.
    Ordinarily, input lines are sent to the server when a
    command-terminating semicolon is reached. An end of line does not
    terminate a command.  Thus commands can be spread over several lines for
    clarity. If the command was sent and executed without error, the results
    of the command are displayed on the screen.
    </para>

    <para>
    Whenever a command is executed, <application>psql</application> also polls
    for asynchronous notification events generated by
    <xref linkend="SQL-LISTEN"> and
    <xref linkend="SQL-NOTIFY">.
    </para>
  </refsect2>

  <refsect2 id="APP-PSQL-meta-commands">
    <title>Meta-Commands</title>

    <para>
    Anything you enter in <application>psql</application> that begins
    with an unquoted backslash is a <application>psql</application>
    meta-command that is processed by <application>psql</application>
    itself. These commands make
    <application>psql</application> more useful for administration or
    scripting. Meta-commands are often called slash or backslash commands.
    </para>

    <para>
    The format of a <application>psql</application> command is the backslash,
    followed immediately by a command verb, then any arguments. The arguments
    are separated from the command verb and each other by any number of
    whitespace characters.
    </para>

    <para>
    To include whitespace into an argument you can quote it with a
    single quote. To include a single quote into such an argument,
    use two single quotes. Anything contained in single quotes is
    furthermore subject to C-like substitutions for
    <literal>\n</literal> (new line), <literal>\t</literal> (tab),
    <literal>\</literal><replaceable>digits</replaceable> (octal), and
    <literal>\x</literal><replaceable>digits</replaceable> (hexadecimal).
    </para>

    <para>
    If an unquoted argument begins with a colon (<literal>:</literal>),
    it is taken as a <application>psql</> variable and the value of the
    variable is used as the argument instead.  If the variable name is
    surrounded by single quotes (e.g. <literal>:'var'</literal>), it
    will be escaped as an SQL literal and the result will be used as
    the argument.  If the variable name is surrounded by double quotes,
    it will be escaped as an SQL identifier and the result will be used
    as the argument.
    </para>

    <para>
    Arguments that are enclosed in backquotes (<literal>`</literal>)
    are taken as a command line that is passed to the shell. The
    output of the command (with any trailing newline removed) is taken
    as the argument value. The above escape sequences also apply in
    backquotes.
    </para>

    <para>
    Some commands take an <acronym>SQL</acronym> identifier (such as a
    table name) as argument. These arguments follow the syntax rules
    of <acronym>SQL</acronym>: Unquoted letters are forced to
    lowercase, while double quotes (<literal>"</>) protect letters
    from case conversion and allow incorporation of whitespace into
    the identifier.  Within double quotes, paired double quotes reduce
    to a single double quote in the resulting name.  For example,
    <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
    and <literal>"A weird"" name"</> becomes <literal>A weird"
    name</>.
    </para>

    <para>
    Parsing for arguments stops at the end of the line, or when another
    unquoted backslash is found.  An unquoted backslash
    is taken as the beginning of a new meta-command. The special
    sequence <literal>\\</literal> (two backslashes) marks the end of
    arguments and continues parsing <acronym>SQL</acronym> commands, if
    any. That way <acronym>SQL</acronym> and
    <application>psql</application> commands can be freely mixed on a
    line. But in any case, the arguments of a meta-command cannot
    continue beyond the end of the line.
    </para>

    <para>
    The following meta-commands are defined:

    <variablelist>
      <varlistentry>
        <term><literal>\a</literal></term>
        <listitem>
        <para>
        If the current table output format is unaligned, it is switched to aligned.
        If it is not unaligned, it is set to unaligned. This command is
        kept for backwards compatibility. See <command>\pset</command> for a
        more general solution.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
       <term><literal>\cd [ <replaceable>directory</replaceable> ]</literal></term>
       <listitem>
        <para>
         Changes the current working directory to
         <replaceable>directory</replaceable>. Without argument, changes
         to the current user's home directory.
        </para>

        <tip>
         <para>
          To print your current working directory, use <literal>\! pwd</literal>.
         </para>
        </tip>
       </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\C [ <replaceable class="parameter">title</replaceable> ]</literal></term>
        <listitem>
        <para>
        Sets the title of any tables being printed as the result of a
        query or unset any such title. This command is equivalent to
        <literal>\pset title <replaceable
        class="parameter">title</replaceable></literal>. (The name of
        this command derives from <quote>caption</quote>, as it was
        previously only used to set the caption in an
        <acronym>HTML</acronym> table.)
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\connect</literal> (or <literal>\c</literal>) <literal>[ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">host</replaceable> ] [ <replaceable class="parameter">port</replaceable> ] ]</literal></term>
        <listitem>
        <para>
        Establishes a new connection to a <productname>PostgreSQL</>
        server. If the new connection is successfully made, the
        previous connection is closed. If any of <replaceable
        class="parameter">dbname</replaceable>, <replaceable
        class="parameter">username</replaceable>, <replaceable
        class="parameter">host</replaceable> or <replaceable
        class="parameter">port</replaceable> are omitted or specified
        as <literal>-</literal>, the value of that parameter from the
        previous connection is used. If there is no previous
        connection, the <application>libpq</application> default for
        the parameter's value is used.
        </para>

        <para>
        If the connection attempt failed (wrong user name, access
        denied, etc.), the previous connection will only be kept if
        <application>psql</application> is in interactive mode. When
        executing a non-interactive script, processing will
        immediately stop with an error. This distinction was chosen as
        a user convenience against typos on the one hand, and a safety
        mechanism that scripts are not accidentally acting on the
        wrong database on the other hand.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\conninfo</literal></term>
        <listitem>
        <para>
        Outputs information about the current database connection.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\copy { <replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column_list</replaceable> ) ] | ( <replaceable class="parameter">query</replaceable> ) }
        { <literal>from</literal> | <literal>to</literal> }
        { <replaceable class="parameter">filename</replaceable> | stdin | stdout | pstdin | pstdout }
        [ with ]
            [ binary ]
            [ oids ]
            [ delimiter [ as ] '<replaceable class="parameter">character</replaceable>' ]
            [ null [ as ] '<replaceable class="parameter">string</replaceable>' ]
            [ csv
              [ header ]
              [ quote [ as ] '<replaceable class="parameter">character</replaceable>' ]
              [ escape [ as ] '<replaceable class="parameter">character</replaceable>' ]
              [ force quote <replaceable class="parameter">column_list</replaceable> | * ]
              [ force not null <replaceable class="parameter">column_list</replaceable> ] ]</literal>
        </term>

        <listitem>
        <para>
        Performs a frontend (client) copy. This is an operation that
        runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY">
        command, but instead of the server
        reading or writing the specified file,
        <application>psql</application> reads or writes the file and
        routes the data between the server and the local file system.
        This means that file accessibility and privileges are those of
        the local user, not the server, and no SQL superuser
        privileges are required.
        </para>

        <para>
        The syntax of the command is similar to that of the
        <acronym>SQL</acronym> <xref linkend="sql-copy">
        command.  Note that, because of this,
        special parsing rules apply to the <command>\copy</command>
        command. In particular, the variable substitution rules and
        backslash escapes do not apply.
        </para>

        <para>
        <literal>\copy ... from stdin | to stdout</literal>
        reads/writes based on the command input and output respectively.
        All rows are read from the same source that issued the command,
        continuing until <literal>\.</literal> is read or the stream
        reaches <acronym>EOF</>. Output is sent to the same place as
        command output. To read/write from
        <application>psql</application>'s standard input or output, use
        <literal>pstdin</> or <literal>pstdout</>. This option is useful
        for populating tables in-line within a SQL script file.
        </para>

        <tip>
        <para>
        This operation is not as efficient as the <acronym>SQL</acronym>
        <command>COPY</command> command because all data must pass
        through the client/server connection. For large
        amounts of data the <acronym>SQL</acronym> command might be preferable.
        </para>
        </tip>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\copyright</literal></term>
        <listitem>
        <para>
        Shows the copyright and distribution terms of
        <productname>PostgreSQL</productname>.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\d[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        For each relation (table, view, index, or sequence) matching the
        <replaceable class="parameter">pattern</replaceable>, show all
        columns, their types, the tablespace (if not the default) and any
        special attributes such as <literal>NOT NULL</literal> or defaults.
        Associated indexes, constraints, rules, and triggers are
        also shown.
        (<quote>Matching the pattern</> is defined in
        <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">
        below.)
        </para>

        <para>
        The command form <literal>\d+</literal> is identical, except that
        more information is displayed: any comments associated with the
        columns of the table are shown, as is the presence of OIDs in the
        table, and the view definition if the relation is a view.
        </para>

        <para>
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>

        <note>
        <para>
        If <command>\d</command> is used without a
        <replaceable class="parameter">pattern</replaceable> argument, it is
        equivalent to <command>\dtvs</command> which will show a list of
        all visible tables, views, and sequences. This is purely a convenience
        measure.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\da[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        Lists aggregate functions, together with their
        return type and the data types they operate on. If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only aggregates whose names match the pattern are shown.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\db[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        Lists tablespaces. If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only tablespaces whose names match the pattern are shown.
        If <literal>+</literal> is appended to the command name, each object
        is listed with its associated permissions.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dc[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists conversions between character-set encodings.
        If <replaceable class="parameter">pattern</replaceable>
        is specified, only conversions whose names match the pattern are
        listed.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dC [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists type casts.
        If <replaceable class="parameter">pattern</replaceable>
        is specified, only casts whose source or target types match the
        pattern are listed.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dd[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Shows the descriptions of objects matching the <replaceable
        class="parameter">pattern</replaceable>, or of all visible objects if
        no argument is given.  But in either case, only objects that have
        a description are listed.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        <quote>Object</quote> covers aggregates, functions, operators,
        types, relations (tables, views, indexes, sequences), large
        objects, rules, and triggers. For example:
<programlisting>
=&gt; <userinput>\dd version</userinput>
                     Object descriptions
   Schema   |  Name   |  Object  |        Description
------------+---------+----------+---------------------------
 pg_catalog | version | function | PostgreSQL version string
(1 row)
</programlisting>
        </para>

        <para>
        Descriptions for objects can be created with the <xref
        linkend="sql-comment">
        <acronym>SQL</acronym> command.
       </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\ddp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists default access privilege settings.  An entry is shown for
        each role (and schema, if applicable) for which the default
        privilege settings have been changed from the built-in defaults.
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only entries whose role name or schema name matches
        the pattern are listed.
        </para>

        <para>
        The <xref linkend="sql-alterdefaultprivileges"> command is used to set
        default access privileges.  The meaning of the
        privilege display is explained under
        <xref linkend="sql-grant">.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dD[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists domains. If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only domains whose names match the pattern are shown.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\des[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists foreign servers (mnemonic: <quote>external
        servers</quote>).
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only those servers whose name matches the pattern
        are listed.  If the form <literal>\des+</literal> is used, a
        full description of each server is shown, including the
        server's ACL, type, version, and options.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\deu[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists user mappings (mnemonic: <quote>external
        users</quote>).
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only those mappings whose user names match the
        pattern are listed.  If the form <literal>\deu+</literal> is
        used, additional information about each mapping is shown.
        </para>

        <caution>
        <para>
        <literal>\deu+</literal> might also display the user name and
        password of the remote user, so care should be taken not to
        disclose them.
        </para>
        </caution>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dew[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists foreign-data wrappers (mnemonic: <quote>external
        wrappers</quote>).
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only those foreign-data wrappers whose name matches
        the pattern are listed.  If the form <literal>\dew+</literal>
        is used, the ACL and options of the foreign-data wrapper are
        also shown.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\df[antwS+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        Lists functions, together with their arguments, return types, and
        function types, which are classified as <quote>agg</> (aggregate),
        <quote>normal</>, <quote>trigger</>, or <quote>window</>.
        To display only functions
        of specific type(s), add the corresponding letters <literal>a</>,
        <literal>n</>, <literal>t</>, or <literal>w</> to the command.
        If <replaceable
        class="parameter">pattern</replaceable> is specified, only
        functions whose names match the pattern are shown.  If the
        form <literal>\df+</literal> is used, additional information
        about each function, including volatility, language, source
        code and description, is shown.  By default, only user-created
        objects are shown; supply a pattern or the <literal>S</literal>
        modifier to include system objects.
        </para>

        <tip>
        <para>
        To look up functions taking arguments or returning values of a specific
        type, use your pager's search capability to scroll through the
        <literal>\df</> output.
        </para>
        </tip>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\dF[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
         Lists text search configurations.
         If <replaceable class="parameter">pattern</replaceable> is specified,
         only configurations whose names match the pattern are shown.
         If the form <literal>\dF+</literal> is used, a full description of
         each configuration is shown, including the underlying text search
         parser and the dictionary list for each parser token type.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\dFd[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
         Lists text search dictionaries.
         If <replaceable class="parameter">pattern</replaceable> is specified,
         only dictionaries whose names match the pattern are shown.
         If the form <literal>\dFd+</literal> is used, additional information
         is shown about each selected dictionary, including the underlying
         text search template and the option values.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\dFp[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
         Lists text search parsers.
         If <replaceable class="parameter">pattern</replaceable> is specified,
         only parsers whose names match the pattern are shown.
         If the form <literal>\dFp+</literal> is used, a full description of
         each parser is shown, including the underlying functions and the
         list of recognized token types.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\dFt[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
         Lists text search templates.
         If <replaceable class="parameter">pattern</replaceable> is specified,
         only templates whose names match the pattern are shown.
         If the form <literal>\dFt+</literal> is used, additional information
         is shown about each template, including the underlying function names.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dg[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists database roles. If <replaceable
        class="parameter">pattern</replaceable> is specified, only
        those roles whose names match the pattern are listed.
        (This command is now effectively the same as <literal>\du</literal>).
        If the form <literal>\dg+</literal> is used, additional information
        is shown about each role, including the comment for each role.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\di[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <term><literal>\ds[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <term><literal>\dt[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <term><literal>\dv[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        In this group of commands, the letters
        <literal>i</literal>, <literal>s</literal>,
        <literal>t</literal>, and <literal>v</literal>
        stand for index, sequence, table, and view, respectively.
        You can specify any or all of
        these letters, in any order, to obtain a listing of objects
        of these types.  For example, <literal>\dit</> lists indexes
        and tables.  If <literal>+</literal> is
        appended to the command name, each object is listed with its
        physical size on disk and its associated description, if any.
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only objects whose names match the pattern are listed.
        By default, only user-created objects are shown; supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dl</literal></term>
        <listitem>
        <para>
        This is an alias for <command>\lo_list</command>, which shows a
        list of large objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dn[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>

        <listitem>
        <para>
        Lists schemas (namespaces). If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only schemas whose names match the pattern are listed.
        Non-local temporary schemas are suppressed.  If <literal>+</literal>
        is appended to the command name, each object is listed with its associated
        permissions and description, if any.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\do[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists operators with their operand and return types.
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only operators whose names match the pattern are listed.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists tables, views and sequences with their
        associated access privileges.
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only tables, views and sequences whose names match the
        pattern are listed.
        </para>

        <para>
        The <xref linkend="sql-grant"> and
        <xref linkend="sql-revoke">
        commands are used to set access privileges.  The meaning of the
        privilege display is explained under
        <xref linkend="sql-grant">.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\drds [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">role-pattern</replaceable></link> [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">database-pattern</replaceable></link> ] ]</literal></term>
        <listitem>
        <para>
        Lists defined configuration settings.  These settings can be
        role-specific, database-specific, or both.
        <replaceable>role-pattern</replaceable> and
        <replaceable>database-pattern</replaceable> are used to select
        specific roles and databases to list, respectively.  If omitted, or if
        <literal>*</> is specified, all settings are listed, including those
        not role-specific or database-specific, respectively.
        </para>

        <para>
        The <xref linkend="sql-alterrole"> and
        <xref linkend="sql-alterdatabase">
        commands are used to define per-role and per-database configuration
        settings.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\dT[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists data types.
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only types whose names match the pattern are listed.
        If <literal>+</literal> is appended to the command name, each type is
        listed with its internal name and size, as well as its allowed values
        if it is an <type>enum</> type.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\du[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists database roles. If <replaceable
        class="parameter">pattern</replaceable> is specified, only
        those roles whose names match the pattern are listed.
        If the form <literal>\du+</literal> is used, additional information
        is shown about each role, including the comment for each role.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\edit</> (or <literal>\e</>) <literal> <optional> <replaceable class="parameter">filename</> </optional> <optional> <replaceable class="parameter">line_number</> </optional> </literal></term>

        <listitem>
        <para>
        If <replaceable class="parameter">filename</replaceable> is
        specified, the file is edited; after the editor exits, its
        content is copied back to the query buffer. If no <replaceable
        class="parameter">filename</replaceable> is given, the current query
        buffer is copied to a temporary file which is then edited in the same
        fashion.
        </para>

        <para>
        The new query buffer is then re-parsed according to the normal
        rules of <application>psql</application>, where the whole buffer
        is treated as a single line. (Thus you cannot make scripts this
        way. Use <command>\i</command> for that.) This means that
        if the query ends with (or contains) a semicolon, it is
        immediately executed. Otherwise it will merely wait in the
        query buffer; type semicolon or <literal>\g</> to send it, or
        <literal>\r</> to cancel.
        </para>

        <tip>
        <para>
        <application>psql</application> checks the environment
        variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
        <envar>VISUAL</envar> (in that order) for an editor to use. If
        all of them are unset, <filename>vi</filename> is used on Unix
        systems, <filename>notepad.exe</filename> on Windows systems.
        </para>
        </tip>

        <para>
        If a line number is specified, <application>psql</application> will
        position the cursor on the specified line of the file or query buffer.
        This feature requires the <varname>EDITOR_LINENUMBER_SWITCH</varname>
        variable to be set, so that <application>psql</application> knows how
        to specify the line number to the editor.  Note that if a single
        all-digits argument is given, <application>psql</application> assumes
        it is a line number not a file name.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\ef <optional> <replaceable class="parameter">function_description</> <optional>  <replaceable class="parameter">line_number</> </optional> </optional> </literal></term>

        <listitem>
        <para>
         This command fetches and edits the definition of the named function,
         in the form of a <command>CREATE OR REPLACE FUNCTION</> command.
         Editing is done in the same way as for <literal>\edit</>.
         After the editor exits, the updated command waits in the query buffer;
         type semicolon or <literal>\g</> to send it, or <literal>\r</>
         to cancel.
        </para>

        <para>
         The target function can be specified by name alone, or by name
         and arguments, for example <literal>foo(integer, text)</>.
         The argument types must be given if there is more
         than one function of the same name.
        </para>

        <para>
         If no function is specified, a blank <command>CREATE FUNCTION</>
         template is presented for editing.
        </para>

        <para>
        If a line number is specified, <application>psql</application> will
        position the cursor on the specified line of the function body
        (note that the function body typically does not begin on the
        first line of the file).
        This feature requires the <varname>EDITOR_LINENUMBER_SWITCH</varname>
        variable to be set, so that <application>psql</application> knows how
        to specify the line number to the editor.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\echo <replaceable class="parameter">text</replaceable> [ ... ]</literal></term>
        <listitem>
        <para>
        Prints the arguments to the standard output, separated by one
        space and followed by a newline. This can be useful to
        intersperse information in the output of scripts. For example:
<programlisting>
=&gt; <userinput>\echo `date`</userinput>
Tue Oct 26 21:40:57 CEST 1999
</programlisting>
        If the first argument is an unquoted <literal>-n</literal> the trailing
        newline is not written.
        </para>

        <tip>
        <para>
        If you use the <command>\o</command> command to redirect your
        query output you might wish to use <command>\qecho</command>
        instead of this command.
        </para>
        </tip>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\encoding [ <replaceable class="parameter">encoding</replaceable> ]</literal></term>

        <listitem>
        <para>
        Sets the client character set encoding.  Without an argument, this command
        shows the current encoding.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\f [ <replaceable class="parameter">string</replaceable> ]</literal></term>

        <listitem>
        <para>
        Sets the field separator for unaligned query output. The default
        is the vertical bar (<literal>|</literal>). See also
        <command>\pset</command> for a generic way of setting output
        options.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>

        <listitem>
        <para>
        Sends the current query input buffer to the server and
        optionally stores the query's output in <replaceable
        class="parameter">filename</replaceable> or pipes the output
        into a separate Unix shell executing <replaceable
        class="parameter">command</replaceable>. A bare
        <literal>\g</literal> is virtually equivalent to a semicolon. A
        <literal>\g</literal> with argument is a <quote>one-shot</quote>
        alternative to the <command>\o</command> command.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\help</literal> (or <literal>\h</literal>) <literal>[ <replaceable class="parameter">command</replaceable> ]</literal></term>
        <listitem>
        <para>
        Gives syntax help on the specified <acronym>SQL</acronym>
        command. If <replaceable class="parameter">command</replaceable>
        is not specified, then <application>psql</application> will list
        all the commands for which syntax help is available. If
        <replaceable class="parameter">command</replaceable> is an
        asterisk (<literal>*</literal>), then syntax help on all
        <acronym>SQL</acronym> commands is shown.
        </para>

        <note>
        <para>
        To simplify typing, commands that consists of several words do
        not have to be quoted. Thus it is fine to type <userinput>\help
        alter table</userinput>.
        </para>
        </note>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\H</literal></term>
        <listitem>
        <para>
        Turns on <acronym>HTML</acronym> query output format. If the
        <acronym>HTML</acronym> format is already on, it is switched
        back to the default aligned text format. This command is for
        compatibility and convenience, but see <command>\pset</command>
        about setting other output options.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\i <replaceable class="parameter">filename</replaceable></literal></term>
        <listitem>
        <para>
        Reads input from the file <replaceable
        class="parameter">filename</replaceable> and executes it as
        though it had been typed on the keyboard.
        </para>
        <note>
        <para>
        If you want to see the lines on the screen as they are read you
        must set the variable <varname>ECHO</varname> to
        <literal>all</literal>.
        </para>
        </note>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\l</literal> (or <literal>\list</literal>)</term>
        <term><literal>\l+</literal> (or <literal>\list+</literal>)</term>
        <listitem>
        <para>
        List the names, owners, character set encodings, and access privileges
        of all the databases in the server.
        If <literal>+</literal> is appended to the command name, database
        sizes, default tablespaces, and descriptions are also displayed.
        (Size information is only available for databases that the current
        user can connect to.)
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\lo_export <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></literal></term>

        <listitem>
        <para>
        Reads the large object with <acronym>OID</acronym> <replaceable
        class="parameter">loid</replaceable> from the database and
        writes it to <replaceable
        class="parameter">filename</replaceable>. Note that this is
        subtly different from the server function
        <function>lo_export</function>, which acts with the permissions
        of the user that the database server runs as and on the server's
        file system.
        </para>
        <tip>
        <para>
        Use <command>\lo_list</command> to find out the large object's
        <acronym>OID</acronym>.
        </para>
        </tip>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\lo_import <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</literal></term>

        <listitem>
        <para>
        Stores the file into a <productname>PostgreSQL</productname>
        large object. Optionally, it associates the given
        comment with the object. Example:
<programlisting>
foo=&gt; <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
lo_import 152801
</programlisting>
        The response indicates that the large object received object
        ID 152801, which can be used to access the newly-created large
        object in the future. For the sake of readability, it is
        recommended to always associate a human-readable comment with
        every object. Both OIDs and comments can be viewed with the
        <command>\lo_list</command> command.
        </para>

        <para>
        Note that this command is subtly different from the server-side
        <function>lo_import</function> because it acts as the local user
        on the local file system, rather than the server's user and file
        system.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\lo_list</literal></term>
        <listitem>
        <para>
        Shows a list of all <productname>PostgreSQL</productname>
        large objects currently stored in the database,
        along with any comments provided for them.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\lo_unlink <replaceable class="parameter">loid</replaceable></literal></term>

        <listitem>
        <para>
        Deletes the large object with <acronym>OID</acronym>
        <replaceable class="parameter">loid</replaceable> from the
        database.
        </para>

        <tip>
        <para>
        Use <command>\lo_list</command> to find out the large object's
        <acronym>OID</acronym>.
        </para>
        </tip>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>

        <listitem>
        <para>
        Saves future query results to the file <replaceable
        class="parameter">filename</replaceable> or pipes future results
        into a separate Unix shell to execute <replaceable
        class="parameter">command</replaceable>. If no arguments are
        specified, the query output will be reset to the standard output.
        </para>

        <para>
        <quote>Query results</quote> includes all tables, command
        responses, and notices obtained from the database server, as
        well as output of various backslash commands that query the
        database (such as <command>\d</command>), but not error
        messages.
        </para>

        <tip>
        <para>
        To intersperse text output in between query results, use
        <command>\qecho</command>.
        </para>
        </tip>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\p</literal></term>
        <listitem>
        <para>
        Print the current query buffer to the standard output.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\password [ <replaceable class="parameter">username</replaceable> ]</literal></term>
        <listitem>
        <para>
        Changes the password of the specified user (by default, the current
        user).  This command prompts for the new password, encrypts it, and
        sends it to the server as an <command>ALTER ROLE</> command.  This
        makes sure that the new password does not appear in cleartext in the
        command history, the server log, or elsewhere.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\prompt [ <replaceable class="parameter">text</replaceable> ] <replaceable class="parameter">name</replaceable></literal></term>
        <listitem>
        <para>
         Prompts the user to set variable <replaceable
         class="parameter">name</>.  An optional prompt, <replaceable
         class="parameter">text</>, can be specified.  (For multiword
         prompts, use single quotes.)
        </para>

        <para>
         By default, <literal>\prompt</> uses the terminal for input and
         output.  However, if the <option>-f</> command line switch is
         used, <literal>\prompt</> uses standard input and standard output.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>\pset <replaceable class="parameter">option</replaceable> [ <replaceable class="parameter">value</replaceable> ]</literal></term>

        <listitem>
        <para>
        This command sets options affecting the output of query result tables.
        <replaceable class="parameter">option</replaceable>
        indicates which option is to be set. The semantics of
        <replaceable class="parameter">value</replaceable> vary depending
        on the selected option.  For some options, omitting <replaceable
        class="parameter">value</replaceable> causes the option to be toggled
        or unset, as described under the particular option.  If no such
        behavior is mentioned, then omitting
        <replaceable class="parameter">value</replaceable> just results in
        the current setting being displayed.
        </para>

        <para>
        Adjustable printing options are:
        <variablelist>
          <varlistentry>
          <term><literal>format</literal></term>
          <listitem>
          <para>
          Sets the output format to one of <literal>unaligned</literal>,
          <literal>aligned</literal>, <literal>wrapped</literal>,
          <literal>html</literal>,
          <literal>latex</literal>, or <literal>troff-ms</literal>.
          Unique abbreviations are allowed.  (That would mean one letter
          is enough.)
          </para>

          <para>
          <literal>unaligned</> format writes all columns of a row on one
          line, separated by the currently active field separator. This
          is useful for creating output that might be intended to be read
          in by other programs (for example, tab-separated or comma-separated
          format).
          </para>

          <para>
          <literal>aligned</literal> format is the standard, human-readable,
          nicely formatted text output;  this is the default.
          </para>

          <para>
          <literal>wrapped</> format is like <literal>aligned</> but wraps
          wide data values across lines to make the output fit in the target
          column width.  The target width is determined as described under
          the <literal>columns</> option.  Note that <application>psql</> will
          not attempt to wrap column header titles; therefore,
          <literal>wrapped</> format behaves the same as <literal>aligned</>
          if the total width needed for column headers exceeds the target.
          </para>

          <para>
          The <literal>html</>, <literal>latex</>, and <literal>troff-ms</>
          formats put out tables that are intended to
          be included in documents using the respective mark-up
          language. They are not complete documents! (This might not be
          so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
          have a complete document wrapper.)
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>columns</literal></term>
          <listitem>
          <para>
          Sets the target width for the <literal>wrapped</> format, and also
          the width limit for determining whether output is wide enough to
          require the pager.
          Zero (the default) causes the target width to be controlled by the
          environment variable <envar>COLUMNS</>, or the detected screen width
          if <envar>COLUMNS</> is not set.
          In addition, if <literal>columns</> is zero then the
          <literal>wrapped</> format only affects screen output.
          If <literal>columns</> is nonzero then file and pipe output is
          wrapped to that width as well.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>border</literal></term>
          <listitem>
          <para>
          The <replaceable class="parameter">value</replaceable> must be a
          number. In general, the higher
          the number the more borders and lines the tables will have,
          but this depends on the particular format. In
          <acronym>HTML</acronym> format, this will translate directly
          into the <literal>border=...</literal> attribute; in the
          other formats only values 0 (no border), 1 (internal dividing lines),
          and 2 (table frame) make sense.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>linestyle</literal></term>
          <listitem>
          <para>
          Sets the border line drawing style to one
          of <literal>ascii</literal>, <literal>old-ascii</literal>
          or <literal>unicode</literal>.
          Unique abbreviations are allowed.  (That would mean one
          letter is enough.)
          The default setting is <literal>ascii</>.
          This option only affects the <literal>aligned</> and
          <literal>wrapped</> output formats.
          </para>

          <para>
          <literal>ascii</literal> style uses plain <acronym>ASCII</acronym>
          characters.  Newlines in data are shown using
          a <literal>+</literal> symbol in the right-hand margin.
          When the <literal>wrapped</literal> format wraps data from
          one line to the next without a newline character, a dot
          (<literal>.</>) is shown in the right-hand margin of the first line,
          and again in the left-hand margin of the following line.
          </para>

          <para>
          <literal>old-ascii</literal> style uses plain <acronym>ASCII</>
          characters, using the formatting style used
          in <productname>PostgreSQL</productname> 8.4 and earlier.
          Newlines in data are shown using a <literal>:</literal>
          symbol in place of the left-hand column separator.
          When the data is wrapped from one line
          to the next without a newline character, a <literal>;</>
          symbol is used in place of the left-hand column separator.
          </para>

          <para>
          <literal>unicode</literal> style uses Unicode box-drawing characters.
          Newlines in data are shown using a carriage return symbol
          in the right-hand margin.  When the data is wrapped from one line
          to the next without a newline character, an ellipsis symbol
          is shown in the right-hand margin of the first line, and
          again in the left-hand margin of the following line.
          </para>

          <para>
          When the <literal>border</> setting is greater than zero,
          this option also determines the characters
          with which the border lines are drawn.
          Plain <acronym>ASCII</acronym> characters work everywhere, but
          Unicode characters look nicer on displays that recognize them.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>expanded</literal> (or <literal>x</literal>)</term>
          <listitem>
          <para>
          If <replaceable class="parameter">value</replaceable> is specified
          it must be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable expanded mode.  If <replaceable
          class="parameter">value</replaceable> is omitted the command toggles
          between regular and expanded mode.
          When expanded mode is enabled, query results
          are displayed in two columns, with the column name on the left and
          the data on the right. This mode is useful if the data wouldn't fit
          on the screen in the normal <quote>horizontal</quote> mode.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>null</literal></term>
          <listitem>
          <para>
          Sets the string to be printed in place of a null value.
          The default is to print nothing, which can easily be mistaken for
          an empty string. For example, one might prefer <literal>\pset null
          '(null)'</literal>.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>fieldsep</literal></term>
          <listitem>
          <para>
          Specifies the field separator to be used in unaligned output
          format. That way one can create, for example, tab- or
          comma-separated output, which other programs might prefer. To
          set a tab as field separator, type <literal>\pset fieldsep
          '\t'</literal>. The default field separator is
          <literal>'|'</literal> (a vertical bar).
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>footer</literal></term>
          <listitem>
          <para>
          If <replaceable class="parameter">value</replaceable> is specified
          it must be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable display of the table footer
          (the <literal>(<replaceable>n</> rows)</literal> count).
          If <replaceable class="parameter">value</replaceable> is omitted the
          command toggles footer display on or off.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>numericlocale</literal></term>
          <listitem>
          <para>
          If <replaceable class="parameter">value</replaceable> is specified
          it must be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable display of a locale-specific character
          to separate groups of digits to the left of the decimal marker.
          If <replaceable class="parameter">value</replaceable> is omitted the
          command toggles between regular and locale-specific numeric output.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>recordsep</literal></term>
          <listitem>
          <para>
          Specifies the record (line) separator to use in unaligned
          output format. The default is a newline character.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
          <listitem>
          <para>
          If <replaceable class="parameter">value</replaceable> is specified
          it must be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable tuples-only mode.
          If <replaceable class="parameter">value</replaceable> is omitted the
          command toggles between regular and tuples-only output.
          Regular output includes extra information such
          as column headers, titles, and various footers. In tuples-only
          mode, only actual table data is shown.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>title</literal></term>
          <listitem>
          <para>
          Sets the table title for any subsequently printed tables. This
          can be used to give your output descriptive tags. If no
          <replaceable class="parameter">value</replaceable> is given,
          the title is unset.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>tableattr</literal> (or <literal>T</literal>)</term>
          <listitem>
          <para>
          Specifies attributes to be placed inside the
          <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag in
          <literal>html</> output format. This
          could for example be <literal>cellpadding</literal> or
          <literal>bgcolor</literal>. Note that you probably don't want
          to specify <literal>border</literal> here, as that is already
          taken care of by <literal>\pset border</literal>.
          If no
          <replaceable class="parameter">value</replaceable> is given,
          the table attributes are unset.
          </para>
          </listitem>
          </varlistentry>

          <varlistentry>
          <term><literal>pager</literal></term>
          <listitem>
          <para>
          Controls use of a pager program for query and <application>psql</>
          help output. If the environment variable <envar>PAGER</envar>
          is set, the output is piped to the specified program.
          Otherwise a platform-dependent default (such as
          <filename>more</filename>) is used.
          </para>

          <para>
          When the <literal>pager</> option is <literal>off</>, the pager
          program is not used. When the <literal>pager</> option is
          <literal>on</>, the pager is used when appropriate, i.e., when the
          output is to a terminal and will not fit on the screen.
          The <literal>pager</> option can also be set to <literal>always</>,
          which causes the pager to be used for all terminal output regardless
          of whether it fits on the screen.  <literal>\pset pager</>
          without a <replaceable class="parameter">value</replaceable>
          toggles pager use on and off.
          </para>
          </listitem>
          </varlistentry>
        </variablelist>
        </para>

        <para>
        Illustrations of how these different formats look can be seen in
        the <xref linkend="APP-PSQL-examples"
        endterm="APP-PSQL-examples-title"> section.
        </para>

        <tip>
        <para>
        There are various shortcut commands for <command>\pset</command>. See
        <command>\a</command>, <command>\C</command>, <command>\H</command>,
        <command>\t</command>, <command>\T</command>, and <command>\x</command>.
        </para>
        </tip>

        <note>
        <para>
        It is an error to call <command>\pset</command> without any
        arguments. In the future this case might show the current status
        of all printing options.
        </para>
        </note>

        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\q</literal></term>
        <listitem>
        <para>
        Quits the <application>psql</application> program.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\qecho <replaceable class="parameter">text</replaceable> [ ... ] </literal></term>
        <listitem>
        <para>
        This command is identical to <command>\echo</command> except
        that the output will be written to the query output channel, as
        set by <command>\o</command>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\r</literal></term>
        <listitem>
        <para>
        Resets (clears) the query buffer.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\s [ <replaceable class="parameter">filename</replaceable> ]</literal></term>
        <listitem>
        <para>
        Print or save the command line history to <replaceable
        class="parameter">filename</replaceable>. If <replaceable
        class="parameter">filename</replaceable> is omitted, the history
        is written to the standard output. This option is only available
        if <application>psql</application> is configured to use the
        <acronym>GNU</acronym> <application>Readline</application> library.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\set [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ] ] ]</literal></term>

        <listitem>
        <para>
        Sets the internal variable <replaceable
        class="parameter">name</replaceable> to <replaceable
        class="parameter">value</replaceable> or, if more than one value
        is given, to the concatenation of all of them. If no second
        argument is given, the variable is just set with no value. To
        unset a variable, use the <command>\unset</command> command.
        </para>

        <para>
        Valid variable names can contain characters, digits, and
        underscores. See the section <xref
        linkend="APP-PSQL-variables"
        endterm="APP-PSQL-variables-title"> below for details.
        Variable names are case-sensitive.
        </para>

        <para>
        Although you are welcome to set any variable to anything you
        want, <application>psql</application> treats several variables
        as special. They are documented in the section about variables.
        </para>

        <note>
        <para>
        This command is totally separate from the <acronym>SQL</acronym>
        command <xref linkend="SQL-SET">.
        </para>
        </note>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\sf[+] <replaceable class="parameter">function_description</> </literal></term>

        <listitem>
        <para>
         This command fetches and shows the definition of the named function,
         in the form of a <command>CREATE OR REPLACE FUNCTION</> command.
         The definition is printed to the current query output channel,
         as set by <command>\o</command>.
        </para>

        <para>
         The target function can be specified by name alone, or by name
         and arguments, for example <literal>foo(integer, text)</>.
         The argument types must be given if there is more
         than one function of the same name.
        </para>

        <para>
         If <literal>+</literal> is appended to the command name, then the
         output lines are numbered, with the first line of the function body
         being line 1.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\t</literal></term>
        <listitem>
        <para>
        Toggles the display of output column name headings and row count
        footer. This command is equivalent to <literal>\pset
        tuples_only</literal> and is provided for convenience.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\T <replaceable class="parameter">table_options</replaceable></literal></term>
        <listitem>
        <para>
        Specifies attributes to be placed within the
        <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym>
        output format. This command is equivalent to <literal>\pset
        tableattr <replaceable
        class="parameter">table_options</replaceable></literal>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
       <term><literal>\timing [ <replaceable class="parameter">on</replaceable> | <replaceable class="parameter">off</replaceable> ]</literal></term>
        <listitem>
        <para>
         Without parameter, toggles a display of how long each SQL statement
         takes, in milliseconds.  With parameter, sets same.
        </para>
       </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\w</literal> <replaceable class="parameter">filename</replaceable></term>
        <term><literal>\w</literal> <literal>|</><replaceable class="parameter">command</replaceable></term>
        <listitem>
        <para>
        Outputs the current query buffer to the file <replaceable
        class="parameter">filename</replaceable> or pipes it to the Unix
        command <replaceable class="parameter">command</replaceable>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\x</literal></term>
        <listitem>
        <para>
        Toggles expanded table formatting mode. As such it is equivalent to
        <literal>\pset expanded</literal>.
       </para>
       </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\z [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
        <listitem>
        <para>
        Lists tables, views and sequences with their
        associated access privileges.
        If a <replaceable class="parameter">pattern</replaceable> is
        specified, only tables, views and sequences whose names match the
        pattern are listed.
        </para>

        <para>
        This is an alias for <command>\dp</command> (<quote>display
        privileges</quote>).
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\! [ <replaceable class="parameter">command</replaceable> ]</literal></term>
        <listitem>
        <para>
        Escapes to a separate Unix shell or executes the Unix command
        <replaceable class="parameter">command</replaceable>. The
        arguments are not further interpreted; the shell will see them
        as-is.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\?</literal></term>
        <listitem>
        <para>
        Shows help information about the backslash commands.
        </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </para>

  <refsect3 id="APP-PSQL-patterns">
   <title id="APP-PSQL-patterns-title">Patterns</title>

   <indexterm>
    <primary>patterns</primary>
    <secondary>in psql and pg_dump</secondary>
   </indexterm>

  <para>
   The various <literal>\d</> commands accept a <replaceable
   class="parameter">pattern</replaceable> parameter to specify the
   object name(s) to be displayed.  In the simplest case, a pattern
   is just the exact name of the object.  The characters within a
   pattern are normally folded to lower case, just as in SQL names;
   for example, <literal>\dt FOO</> will display the table named
   <literal>foo</>.  As in SQL names, placing double quotes around
   a pattern stops folding to lower case.  Should you need to include
   an actual double quote character in a pattern, write it as a pair
   of double quotes within a double-quote sequence; again this is in
   accord with the rules for SQL quoted identifiers.  For example,
   <literal>\dt "FOO""BAR"</> will display the table named
   <literal>FOO"BAR</> (not <literal>foo"bar</>).  Unlike the normal
   rules for SQL names, you can put double quotes around just part
   of a pattern, for instance <literal>\dt FOO"FOO"BAR</> will display
   the table named <literal>fooFOObar</>.
  </para>

  <para>
   Whenever the <replaceable class="parameter">pattern</replaceable> parameter
   is omitted completely, the <literal>\d</> commands display all objects
   that are visible in the current schema search path &mdash; this is
   equivalent to using <literal>*</> as the pattern.
   (An object is said to be <firstterm>visible</> if its
   containing schema is in the search path and no object of the same
   kind and name appears earlier in the search path. This is equivalent to the
   statement that the object can be referenced by name without explicit
   schema qualification.)
   To see all objects in the database regardless of visibility,
   use <literal>*.*</> as the pattern.
  </para>

  <para>
   Within a pattern, <literal>*</> matches any sequence of characters
   (including no characters) and <literal>?</> matches any single character.
   (This notation is comparable to Unix shell file name patterns.)
   For example, <literal>\dt int*</> displays tables whose names
   begin with <literal>int</>.  But within double quotes, <literal>*</>
   and <literal>?</> lose these special meanings and are just matched
   literally.
  </para>

  <para>
   A pattern that contains a dot (<literal>.</>) is interpreted as a schema
   name pattern followed by an object name pattern.  For example,
   <literal>\dt foo*.*bar*</> displays all tables whose table name
   includes <literal>bar</> that are in schemas whose schema name
   starts with <literal>foo</>.  When no dot appears, then the pattern
   matches only objects that are visible in the current schema search path.
   Again, a dot within double quotes loses its special meaning and is matched
   literally.
  </para>

  <para>
   Advanced users can use regular-expression notations such as character
   classes, for example <literal>[0-9]</> to match any digit.  All regular
   expression special characters work as specified in
   <xref linkend="functions-posix-regexp">, except for <literal>.</> which
   is taken as a separator as mentioned above, <literal>*</> which is
   translated to the regular-expression notation <literal>.*</>,
   <literal>?</> which is translated to <literal>.</>, and
   <literal>$</> which is matched literally.  You can emulate
   these pattern characters at need by writing
   <literal>?</> for <literal>.</>,
   <literal>(<replaceable class="parameter">R</replaceable>+|)</literal> for
   <literal><replaceable class="parameter">R</replaceable>*</literal>, or
   <literal>(<replaceable class="parameter">R</replaceable>|)</literal> for
   <literal><replaceable class="parameter">R</replaceable>?</literal>.
   <literal>$</> is not needed as a regular-expression character since
   the pattern must match the whole name, unlike the usual
   interpretation of regular expressions (in other words, <literal>$</>
   is automatically appended to your pattern).  Write <literal>*</> at the
   beginning and/or end if you don't wish the pattern to be anchored.
   Note that within double quotes, all regular expression special characters
   lose their special meanings and are matched literally.  Also, the regular
   expression special characters are matched literally in operator name
   patterns (i.e., the argument of <literal>\do</>).
  </para>
  </refsect3>
 </refsect2>

 <refsect2>
  <title>Advanced features</title>

   <refsect3 id="APP-PSQL-variables">
    <title id="APP-PSQL-variables-title">Variables</title>

    <para>
    <application>psql</application> provides variable substitution
    features similar to common Unix command shells.
    Variables are simply name/value pairs, where the value
    can be any string of any length. To set variables, use the
    <application>psql</application> meta-command
    <command>\set</command>:
<programlisting>
testdb=&gt; <userinput>\set foo bar</userinput>
</programlisting>
    sets the variable <literal>foo</literal> to the value
    <literal>bar</literal>. To retrieve the content of the variable, precede
    the name with a colon and use it as the argument of any slash
    command:
<programlisting>
testdb=&gt; <userinput>\echo :foo</userinput>
bar
</programlisting>
    </para>

    <note>
    <para>
    The arguments of <command>\set</command> are subject to the same
    substitution rules as with other commands. Thus you can construct
    interesting references such as <literal>\set :foo
    'something'</literal> and get <quote>soft links</quote> or
    <quote>variable variables</quote> of <productname>Perl</productname>
    or <productname><acronym>PHP</acronym></productname> fame,
    respectively. Unfortunately (or fortunately?), there is no way to do
    anything useful with these constructs. On the other hand,
    <literal>\set bar :foo</literal> is a perfectly valid way to copy a
    variable.
    </para>
    </note>

    <para>
    If you call <command>\set</command> without a second argument, the
    variable is set, with an empty string as value. To unset (or delete) a
    variable, use the command <command>\unset</command>.
    </para>

    <para>
    <application>psql</application>'s internal variable names can
    consist of letters, numbers, and underscores in any order and any
    number of them. A number of these variables are treated specially
    by <application>psql</application>. They indicate certain option
    settings that can be changed at run time by altering the value of
    the variable or that represent some state of the application. Although
    you can use these variables for any other purpose, this is not
    recommended, as the program behavior might grow really strange
    really quickly. By convention, all specially treated variables
    consist of all upper-case letters (and possibly numbers and
    underscores). To ensure maximum compatibility in the future, avoid
    using such variable names for your own purposes. A list of all specially
    treated variables follows.
   </para>

    <variablelist>
      <varlistentry>
      <indexterm>
       <primary>autocommit</primary>
       <secondary>psql</secondary>
      </indexterm>
        <term><varname>AUTOCOMMIT</varname></term>
        <listitem>
        <para>
        When <literal>on</> (the default), each SQL command is automatically
        committed upon successful completion.  To postpone commit in this
        mode, you must enter a <command>BEGIN</> or <command>START
        TRANSACTION</> SQL command.  When <literal>off</> or unset, SQL
        commands are not committed until you explicitly issue
        <command>COMMIT</> or <command>END</>.  The autocommit-off
        mode works by issuing an implicit <command>BEGIN</> for you, just
        before any command that is not already in a transaction block and
        is not itself a <command>BEGIN</> or other transaction-control
        command, nor a command that cannot be executed inside a transaction
        block (such as <command>VACUUM</>).
        </para>

        <note>
        <para>
         In autocommit-off mode, you must explicitly abandon any failed
         transaction by entering <command>ABORT</> or <command>ROLLBACK</>.
         Also keep in mind that if you exit the session
         without committing, your work will be lost.
        </para>
        </note>

        <note>
        <para>
         The autocommit-on mode is <productname>PostgreSQL</>'s traditional
         behavior, but autocommit-off is closer to the SQL spec.  If you
         prefer autocommit-off, you might wish to set it in the system-wide
         <filename>psqlrc</filename> file or your
         <filename>~/.psqlrc</filename> file.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>DBNAME</varname></term>
        <listitem>
        <para>
        The name of the database you are currently connected to. This is
        set every time you connect to a database (including program
        start-up), but can be unset.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ECHO</varname></term>
        <listitem>
        <para>
        If set to <literal>all</literal>, all lines
        entered from the keyboard or from a script are written to the standard output
        before they are parsed or executed. To select this behavior on program
        start-up, use the switch <option>-a</option>. If set to
        <literal>queries</literal>,
        <application>psql</application> merely prints all queries as
        they are sent to the server. The switch for this is
        <option>-e</option>.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ECHO_HIDDEN</varname></term>
        <listitem>
        <para>
        When this variable is set and a backslash command queries the
        database, the query is first shown. This way you can study the
        <productname>PostgreSQL</productname> internals and provide
        similar functionality in your own programs. (To select this behavior
        on program start-up, use the switch <option>-E</option>.)  If you set
        the variable to the value <literal>noexec</literal>, the queries are
        just shown but are not actually sent to the server and executed.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>EDITOR_LINENUMBER_SWITCH</varname></term>
        <listitem>
        <para>
        When <command>\edit</command> or <command>\ef</command> is used with a
        line number argument, this variable specifies the command-line switch
        used to pass the line number to the user's editor.  For editors such
        as <productname>emacs</> or <productname>vi</>, you can simply set
        this variable to a plus sign.  Include a trailing space in the value
        of the variable if there needs to be space between the switch name and
        the line number.
        Examples:

<programlisting>
\set EDITOR_LINENUMBER_SWITCH +
\set EDITOR_LINENUMBER_SWITCH '--line '
</programlisting>
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ENCODING</varname></term>
        <listitem>
        <para>
        The current client character set encoding.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>FETCH_COUNT</varname></term>
        <listitem>
        <para>
        If this variable is set to an integer value &gt; 0,
        the results of <command>SELECT</command> queries are fetched
        and displayed in groups of that many rows, rather than the
        default behavior of collecting the entire result set before
        display.  Therefore only a
        limited amount of memory is used, regardless of the size of
        the result set.  Settings of 100 to 1000 are commonly used
        when enabling this feature.
        Keep in mind that when using this feature, a query might
        fail after having already displayed some rows.
        </para>
        <tip>
        <para>
        Although you can use any output format with this feature,
        the default <literal>aligned</> format tends to look bad
        because each group of <varname>FETCH_COUNT</varname> rows
        will be formatted separately, leading to varying column
        widths across the row groups.  The other output formats work better.
        </para>
        </tip>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>HISTCONTROL</varname></term>
        <listitem>
        <para>
         If this variable is set to <literal>ignorespace</literal>,
         lines which begin with a space are not entered into the history
         list. If set to a value of <literal>ignoredups</literal>, lines
         matching the previous history line are not entered. A value of
         <literal>ignoreboth</literal> combines the two options. If
         unset, or if set to any other value than those above, all lines
         read in interactive mode are saved on the history list.
        </para>
        <note>
        <para>
        This feature was shamelessly plagiarized from
        <application>Bash</application>.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>HISTFILE</varname></term>
        <listitem>
        <para>
        The file name that will be used to store the history list. The default
        value is <filename>~/.psql_history</filename>.  For example, putting:
<programlisting>
\set HISTFILE ~/.psql_history- :DBNAME
</programlisting>
        in <filename>~/.psqlrc</filename> will cause
        <application>psql</application> to maintain a separate history for
        each database.
        </para>
        <note>
        <para>
        This feature was shamelessly plagiarized from
        <application>Bash</application>.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>HISTSIZE</varname></term>
        <listitem>
        <para>
        The number of commands to store in the command history. The
        default value is 500.
        </para>
        <note>
        <para>
        This feature was shamelessly plagiarized from
        <application>Bash</application>.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>HOST</varname></term>
        <listitem>
        <para>
        The database server host you are currently connected to. This is
        set every time you connect to a database (including program
        start-up), but can be unset.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>IGNOREEOF</varname></term>
        <listitem>
        <para>
         If unset, sending an <acronym>EOF</> character (usually
         <keycombo action="simul"><keycap>Control</><keycap>D</></>)
         to an interactive session of <application>psql</application>
         will terminate the application. If set to a numeric value,
         that many <acronym>EOF</> characters are ignored before the
         application terminates.  If the variable is set but has no
         numeric value, the default is 10.
        </para>
        <note>
        <para>
        This feature was shamelessly plagiarized from
        <application>Bash</application>.
        </para>
        </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>LASTOID</varname></term>
        <listitem>
        <para>
        The value of the last affected OID, as returned from an
        <command>INSERT</command> or <command>lo_insert</command>
        command. This variable is only guaranteed to be valid until
        after the result of the next <acronym>SQL</acronym> command has
        been displayed.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
      <indexterm>
       <primary>rollback</primary>
       <secondary>psql</secondary>
      </indexterm>
        <term><varname>ON_ERROR_ROLLBACK</varname></term>
        <listitem>
        <para>
        When <literal>on</>, if a statement in a transaction block
        generates an error, the error is ignored and the transaction
        continues. When <literal>interactive</>, such errors are only
        ignored in interactive sessions, and not when reading script
        files. When <literal>off</> (the default), a statement in a
        transaction block that generates an error aborts the entire
        transaction. The on_error_rollback-on mode works by issuing an
        implicit <command>SAVEPOINT</> for you, just before each command
        that is in a transaction block, and rolls back to the savepoint
        on error.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ON_ERROR_STOP</varname></term>
        <listitem>
        <para>
        By default, if non-interactive scripts encounter an error, such
        as a malformed <acronym>SQL</acronym> command or internal
        meta-command, processing continues. This has been the
        traditional behavior of <application>psql</application> but it
        is sometimes not desirable. If this variable is set, script
        processing will immediately terminate. If the script was called
        from another script it will terminate in the same fashion. If
        the outermost script was not called from an interactive
        <application>psql</application> session but rather using the
        <option>-f</option> option, <application>psql</application> will
        return error code 3, to distinguish this case from fatal error
        conditions (error code 1).
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PORT</varname></term>
        <listitem>
        <para>
        The database server port to which you are currently connected.
        This is set every time you connect to a database (including
        program start-up), but can be unset.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PROMPT1</varname></term>
        <term><varname>PROMPT2</varname></term>
        <term><varname>PROMPT3</varname></term>
        <listitem>
        <para>
        These specify what the prompts <application>psql</application>
        issues should look like. See <xref
        linkend="APP-PSQL-prompting"
        endterm="APP-PSQL-prompting-title"> below.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>QUIET</varname></term>
        <listitem>
        <para>
        This variable is equivalent to the command line option
        <option>-q</option>. It is probably not too useful in
        interactive mode.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SINGLELINE</varname></term>
        <listitem>
        <para>
        This variable is equivalent to the command line option
        <option>-S</option>.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SINGLESTEP</varname></term>
        <listitem>
        <para>
        This variable is equivalent to the command line option
        <option>-s</option>.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>USER</varname></term>
        <listitem>
        <para>
        The database user you are currently connected as. This is set
        every time you connect to a database (including program
        start-up), but can be unset.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>VERBOSITY</varname></term>
        <listitem>
        <para>
        This variable can be set to the values <literal>default</>,
        <literal>verbose</>, or <literal>terse</> to control the verbosity
        of error reports.
        </para>
        </listitem>
      </varlistentry>

    </variablelist>

   </refsect3>

   <refsect3>
    <title><acronym>SQL</acronym> Interpolation</title>

    <para>
    An additional useful feature of <application>psql</application>
    variables is that you can substitute (<quote>interpolate</quote>)
    them into regular <acronym>SQL</acronym> statements.
    <application>psql</application> provides special facilities for
    ensuring that values used as SQL literals and identifiers are
    properly escaped.  The syntax for interpolating a value without
    any special escaping is again to prepend the variable name with a colon
    (<literal>:</literal>):
<programlisting>
testdb=&gt; <userinput>\set foo 'my_table'</userinput>
testdb=&gt; <userinput>SELECT * FROM :foo;</userinput>
</programlisting>
    would then query the table <literal>my_table</literal>. Note that this
    may be unsafe: the value of the variable is copied literally, so it can
    even contain unbalanced quotes or backslash commands. You must make sure
    that it makes sense where you put it.
    </para>

    <para>
    When a value is to be used as an SQL literal or identifier, it is
    safest to arrange for it to be escaped.  To escape the value of
    a variable as an SQL literal, write a colon followed by the variable
    name in single quotes.  To escape the value an SQL identifier, write
    a colon followed by the variable name in double quotes.  The previous
    example would be more safely written this way:
<programlisting>
testdb=&gt; <userinput>\set foo 'my_table'</userinput>
testdb=&gt; <userinput>SELECT * FROM :"foo";</userinput>
</programlisting>
    Variable interpolation will not be performed into quoted
    <acronym>SQL</acronym> entities.
    </para>

    <para>
    One  possible use of this mechanism is to
    copy the contents of a file into a table column. First load the file into a
    variable and then proceed as above:
<programlisting>
testdb=&gt; <userinput>\set content `cat my_file.txt`</userinput>
testdb=&gt; <userinput>INSERT INTO my_table VALUES (:'content');</userinput>
</programlisting>
    (Note that this still won't work if <filename>my_file.txt</filename> contains NUL bytes.
    psql does not support embedded NUL bytes in variable values.)
    </para>

    <para>
    Since colons can legally appear in SQL commands, an apparent attempt
    at interpolation (such as <literal>:name</literal>,
    <literal>:'name'</literal>, or <literal>:"name"</literal>) is not
    changed unless the named variable is currently set. In any case, you
    can escape a colon with a backslash to protect it from substitution.
    (The colon syntax for variables is standard <acronym>SQL</acronym> for
    embedded query languages, such as <application>ECPG</application>.
    The colon syntax for array slices and type casts are
    <productname>PostgreSQL</productname> extensions, hence the
    conflict.  The colon syntax for escaping a variable's value as an
    SQL literal or identifier is a <application>psql</application>
    extension.)
    </para>

   </refsect3>

   <refsect3 id="APP-PSQL-prompting">
    <title id="APP-PSQL-prompting-title">Prompting</title>

    <para>
    The prompts <application>psql</application> issues can be customized
    to your preference. The three variables <varname>PROMPT1</varname>,
    <varname>PROMPT2</varname>, and <varname>PROMPT3</varname> contain strings
    and special escape sequences that describe the appearance of the
    prompt. Prompt 1 is the normal prompt that is issued when
    <application>psql</application> requests a new command. Prompt 2 is
    issued when more input is expected during command input because the
    command was not terminated with a semicolon or a quote was not closed.
    Prompt 3 is issued when you run an <acronym>SQL</acronym>
    <command>COPY</command> command and you are expected to type in the
    row values on the terminal.
    </para>

    <para>
    The value of the selected prompt variable is printed literally,
    except where a percent sign (<literal>%</literal>) is encountered.
    Depending on the next character, certain other text is substituted
    instead. Defined substitutions are:

    <variablelist>
      <varlistentry>
        <term><literal>%M</literal></term>
        <listitem>
         <para>
          The full host name (with domain name) of the database server,
          or <literal>[local]</literal> if the connection is over a Unix
          domain socket, or
          <literal>[local:<replaceable>/dir/name</replaceable>]</literal>,
          if the Unix domain socket is not at the compiled in default
          location.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%m</literal></term>
        <listitem>
         <para>
          The host name of the database server, truncated at the
          first dot, or <literal>[local]</literal> if the connection is
          over a Unix domain socket.
         </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%&gt;</literal></term>
        <listitem><para>The port number at which the database server is listening.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%n</literal></term>
        <listitem>
         <para>
          The database session user name.  (The expansion of this
          value might change during a database session as the result
          of the command <command>SET SESSION
          AUTHORIZATION</command>.)
         </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%/</literal></term>
        <listitem><para>The name of the current database.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%~</literal></term>
        <listitem><para>Like <literal>%/</literal>, but the output is <literal>~</literal>
         (tilde) if the database is your default database.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%#</literal></term>
        <listitem>
         <para>
          If the session user is a database superuser, then a
          <literal>#</literal>, otherwise a <literal>&gt;</literal>.
          (The expansion of this value might change during a database
          session as the result of the command <command>SET SESSION
          AUTHORIZATION</command>.)
         </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%R</literal></term>
        <listitem>
        <para>
        In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
        in single-line mode, and <literal>!</literal> if the session is
        disconnected from the database (which can happen if
        <command>\connect</command> fails). In prompt 2 the sequence is
        replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
        a double quote, or a dollar sign, depending on whether
        <application>psql</application> expects more input because the
        command wasn't terminated yet, because you are inside a
        <literal>/* ... */</literal> comment, or because you are inside
        a quoted or dollar-escaped string. In prompt 3 the sequence doesn't
        produce anything.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%x</literal></term>
        <listitem>
        <para>
        Transaction status: an empty string when not in a transaction
        block, or <literal>*</> when in a transaction block, or
        <literal>!</> when in a failed transaction block, or <literal>?</>
        when the transaction state is indeterminate (for example, because
        there is no connection).
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%</literal><replaceable class="parameter">digits</replaceable></term>
        <listitem>
        <para>
        The character with the indicated octal code is substituted.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
        <listitem>
        <para>
        The value of the <application>psql</application> variable
        <replaceable class="parameter">name</replaceable>. See the
        section <xref linkend="APP-PSQL-variables"
        endterm="APP-PSQL-variables-title"> for details.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%`</literal><replaceable class="parameter">command</replaceable><literal>`</literal></term>
        <listitem>
        <para>
        The output of <replaceable
        class="parameter">command</replaceable>, similar to ordinary
        <quote>back-tick</quote> substitution.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>%[</literal> ... <literal>%]</literal></term>
        <listitem>
         <para>
         Prompts can contain terminal control characters which, for
         example, change the color, background, or style of the prompt
         text, or change the title of the terminal window. In order for
         the line editing features of <application>Readline</application> to work properly, these
         non-printing control characters must be designated as invisible
         by surrounding them with <literal>%[</literal> and
         <literal>%]</literal>. Multiple pairs of these can occur within
         the prompt.  For example:
<programlisting>
testdb=&gt; \set PROMPT1 '%[%033[1;33;40m%]%n@@%/%R%[%033[0m%]%# '
</programlisting>
         results in a boldfaced (<literal>1;</literal>) yellow-on-black
         (<literal>33;40</literal>) prompt on VT100-compatible, color-capable
         terminals.
        </para>
        </listitem>
      </varlistentry>

    </variablelist>

    To insert a percent sign into your prompt, write
    <literal>%%</literal>. The default prompts are
    <literal>'%/%R%# '</literal> for prompts 1 and 2, and
    <literal>'&gt;&gt; '</literal> for prompt 3.
    </para>

    <note>
    <para>
    This feature was shamelessly plagiarized from
    <application>tcsh</application>.
    </para>
    </note>

   </refsect3>

   <refsect3>
    <title>Command-Line Editing</title>

    <para>
    <application>psql</application> supports the <application>Readline</application>
    library for convenient line editing and retrieval. The command
    history is automatically saved when <application>psql</application>
    exits and is reloaded when
    <application>psql</application> starts up. Tab-completion is also
    supported, although the completion logic makes no claim to be an
    <acronym>SQL</acronym> parser.  If for some reason you do not like the tab completion, you
    can turn it off by putting this in a file named
    <filename>.inputrc</filename> in your home directory:
<programlisting>
$if psql
set disable-completion on
$endif
</programlisting>
    (This is not a <application>psql</application> but a
    <application>Readline</application> feature. Read its documentation
    for further details.)
    </para>
   </refsect3>
  </refsect2>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>

   <varlistentry>
    <term><envar>COLUMNS</envar></term>

    <listitem>
     <para>
      If <literal>\pset columns</> is zero, controls the
      width for the <literal>wrapped</> format and width for determining
      if wide output requires the pager.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PAGER</envar></term>

    <listitem>
     <para>
      If the query results do not fit on the screen, they are piped
      through this command.  Typical values are
      <literal>more</literal> or <literal>less</literal>.  The default
      is platform-dependent.  The use of the pager can be disabled by
      using the <command>\pset</command> command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGDATABASE</envar></term>
    <term><envar>PGHOST</envar></term>
    <term><envar>PGPORT</envar></term>
    <term><envar>PGUSER</envar></term>

    <listitem>
     <para>
      Default connection parameters (see <xref linkend="libpq-envars">).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PSQL_EDITOR</envar></term>
    <term><envar>EDITOR</envar></term>
    <term><envar>VISUAL</envar></term>

    <listitem>
     <para>
      Editor used by the <command>\e</command> command.  The variables
      are examined in the order listed; the first that is set is used.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>SHELL</envar></term>

    <listitem>
     <para>
      Command executed by the <command>\!</command> command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>TMPDIR</envar></term>

    <listitem>
     <para>
      Directory for storing temporary files.  The default is
      <filename>/tmp</filename>.
     </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>
  <title>Files</title>

  <itemizedlist>
   <listitem>
    <para>
     Unless it is passed an <option>-X</option>
     or <option>-c</option> option,
     <application>psql</application> attempts to
     read and execute commands from the system-wide
     <filename>psqlrc</filename> file and the user's
     <filename>~/.psqlrc</filename> file before starting up.
     (On Windows, the user's startup file is named
     <filename>%APPDATA%\postgresql\psqlrc.conf</filename>.)
     See <filename><replaceable>PREFIX</>/share/psqlrc.sample</>
     for information on setting up the system-wide file.  It could be used
     to set up the client or the server to taste (using the <command>\set
     </command> and <command>SET</command> commands).
    </para>
   </listitem>

   <listitem>
    <para>
     Both the system-wide <filename>psqlrc</filename> file and the user's
     <filename>~/.psqlrc</filename> file can be made version-specific
     by appending a dash and the <productname>PostgreSQL</productname>
     release number, for example <filename>~/.psqlrc-&version;</filename>.
     A matching version-specific file will be read in preference to a
     non-version-specific file.
    </para>
   </listitem>

   <listitem>
    <para>
     The command-line history is stored in the file
     <filename>~/.psql_history</filename>, or
     <filename>%APPDATA%\postgresql\psql_history</filename> on Windows.
    </para>
   </listitem>
  </itemizedlist>
 </refsect1>


 <refsect1>
  <title>Notes</title>

    <itemizedlist>
      <listitem>
      <para>
       In an earlier life <application>psql</application> allowed the
       first argument of a single-letter backslash command to start
       directly after the command, without intervening whitespace.
       As of <productname>PostgreSQL</productname> 8.4 this is no
       longer allowed.
      </para>
      </listitem>

      <listitem>
      <para>
       <application>psql</application> is only guaranteed to work smoothly
       with servers of the same version. That does not mean other combinations
       will fail outright, but subtle and not-so-subtle problems might come
       up.  Backslash commands are particularly likely to fail if the
       server is of a newer version than <application>psql</> itself.  However,
       backslash commands of the <literal>\d</> family should work with
       servers of versions back to 7.4, though not necessarily with servers
       newer than  <application>psql</> itself.
      </para>
      </listitem>

    </itemizedlist>
 </refsect1>


 <refsect1>
  <title>Notes for Windows users</title>

 <para>
  <application>psql</application> is built as a <quote>console
  application</>.  Since the Windows console windows use a different
  encoding than the rest of the system, you must take special care
  when using 8-bit characters within <application>psql</application>.
  If <application>psql</application> detects a problematic
  console code page, it will warn you at startup. To change the
  console code page, two things are necessary:

   <itemizedlist>
    <listitem>
     <para>
      Set the code page by entering <userinput>cmd.exe /c chcp
      1252</userinput>. (1252 is a code page that is appropriate for
      German; replace it with your value.) If you are using Cygwin,
      you can put this command in <filename>/etc/profile</filename>.
     </para>
    </listitem>

    <listitem>
     <para>
      Set the console font to <literal>Lucida Console</>, because the
      raster font does not work with the ANSI code page.
     </para>
    </listitem>
   </itemizedlist>
 </para>

 </refsect1>


 <refsect1 id="APP-PSQL-examples">
  <title id="APP-PSQL-examples-title">Examples</title>

  <para>
  The first example shows how to spread a command over several lines of
  input. Notice the changing prompt:
<programlisting>
testdb=&gt; <userinput>CREATE TABLE my_table (</userinput>
testdb(&gt; <userinput> first integer not null default 0,</userinput>
testdb(&gt; <userinput> second text)</userinput>
testdb-&gt; <userinput>;</userinput>
CREATE TABLE
</programlisting>
  Now look at the table definition again:
<programlisting>
testdb=&gt; <userinput>\d my_table</userinput>
             Table "my_table"
 Attribute |  Type   |      Modifier
-----------+---------+--------------------
 first     | integer | not null default 0
 second    | text    |

</programlisting>
  Now we change the prompt to something more interesting:
<programlisting>
testdb=&gt; <userinput>\set PROMPT1 '%n@@%m %~%R%# '</userinput>
peter@@localhost testdb=&gt;
</programlisting>
  Let's assume you have filled the table with data and want to take a
  look at it:
<programlisting>
peter@@localhost testdb=&gt; SELECT * FROM my_table;
 first | second
-------+--------
     1 | one
     2 | two
     3 | three
     4 | four
(4 rows)

</programlisting>
  You can display tables in different ways by using the
  <command>\pset</command> command:
<programlisting>
peter@@localhost testdb=&gt; <userinput>\pset border 2</userinput>
Border style is 2.
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
+-------+--------+
| first | second |
+-------+--------+
|     1 | one    |
|     2 | two    |
|     3 | three  |
|     4 | four   |
+-------+--------+
(4 rows)

peter@@localhost testdb=&gt; <userinput>\pset border 0</userinput>
Border style is 0.
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
first second
----- ------
    1 one
    2 two
    3 three
    4 four
(4 rows)

peter@@localhost testdb=&gt; <userinput>\pset border 1</userinput>
Border style is 1.
peter@@localhost testdb=&gt; <userinput>\pset format unaligned</userinput>
Output format is unaligned.
peter@@localhost testdb=&gt; <userinput>\pset fieldsep ","</userinput>
Field separator is ",".
peter@@localhost testdb=&gt; <userinput>\pset tuples_only</userinput>
Showing only tuples.
peter@@localhost testdb=&gt; <userinput>SELECT second, first FROM my_table;</userinput>
one,1
two,2
three,3
four,4
</programlisting>
  Alternatively, use the short commands:
<programlisting>
peter@@localhost testdb=&gt; <userinput>\a \t \x</userinput>
Output format is aligned.
Tuples only is off.
Expanded display is on.
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four
</programlisting>
  </para>

 </refsect1>

</refentry>
@


1.249
log
@Add a \sf (show function) command to psql, for those times when you need to
look at a function but don't wish to fire up an editor.

Pavel Stehule, reviewed by Jan Urbanski
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.248 2010/08/12 00:40:59 tgl Exp $
d1046 1
a1046 1
        full desription of each server is shown, including the
d1709 2
a1710 2
         class="parameter">text</>, can be specified.  (For multi-word
         prompts, use single-quotes.)
d2839 1
a2839 1
    (Note that this still won't work if my_file.txt contains NUL bytes.
@


1.248
log
@Extend psql's \e and \ef commands so that a line number can be specified,
and the editor's cursor will be initially placed on that line.  In \e the
lines are counted with respect to the query buffer, while in \ef they are
counted with line 1 = first line of function body.  These choices are useful
for positioning the cursor on the line of a previously-reported error.

To avoid assumptions about what switch the user's editor takes for this
purpose, invent a new psql variable EDITOR_LINENUMBER_SWITCH with (at
present) no default value.

One incompatibility from previous behavior is that "\e 1234" will now
take "1234" as a line number not a file name.  There are at least two
ways to select a numerically-named file if you really want to.

Pavel Stehule, reviewed by Jan Urbanski, with further editing by Robert Haas
and Tom Lane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.247 2010/08/03 18:33:09 tgl Exp $
d2140 27
@


1.247
log
@Kibitzing on \conninfo patch: adjust the order of field output to match
the parameters of \connect, and fix oversight of not enabling translation
of the messages.  Also, adjust \connect's similar messages to match, and
deal with 8.2-era violation of basic translatability guidelines there.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.246 2010/07/20 03:54:19 rhaas Exp $
d1341 1
a1341 1
        <term><literal>\edit</literal> (or <literal>\e</literal>) <literal><optional> <replaceable class="parameter">filename</replaceable> </optional></literal></term>
d1347 4
a1350 3
        content is copied back to the query buffer. If no argument is
        given, the current query buffer is copied to a temporary file
        which is then edited in the same fashion.
d1357 5
a1361 4
        way. Use <command>\i</command> for that.) This means also that
        if the query ends with (or rather contains) a semicolon, it is
        immediately executed. In other cases it will merely wait in the
        query buffer.
d1366 1
a1366 1
        <application>psql</application> searches the environment
d1373 10
d1388 1
a1388 1
        <term><literal>\ef <optional> <replaceable class="parameter">function_description</replaceable> </optional></literal></term>
d1394 1
a1394 1
         Editing is done in the same way as for <literal>\e</>.
d1411 10
d2483 21
@


1.246
log
@Add \conninfo command to psql, to show current connection info.

David Christensen. Reviewed by Steve Singer.  Some further changes by me.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.245 2010/07/10 00:50:24 rhaas Exp $
d787 1
a787 2
        Outputs connection information about the current database
        connection.
@


1.245
log
@Clarify that "psql -c" ignores psqlrc files.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.244 2010/04/03 07:23:02 petere Exp $
d784 10
@


1.244
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.243 2010/03/21 00:43:40 momjian Exp $
d82 3
a84 1
      and then exit. This is useful in shell scripts.
d3095 3
a3097 1
     Before starting up, <application>psql</application> attempts to
d3100 1
a3100 1
     <filename>~/.psqlrc</filename> file.
@


1.244.2.1
log
@Clarify that "psql -c" ignores psqlrc files.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.244 2010/04/03 07:23:02 petere Exp $
d82 1
a82 3
      and then exit. This is useful in shell scripts. Start-up files
      (<filename>psqlrc</filename> and <filename>~/.psqlrc</filename>) are
      ignored with this option.
d3093 1
a3093 3
     Unless it is passed an <option>-X</option>
     or <option>-c</option> option,
     <application>psql</application> attempts to
d3096 1
a3096 1
     <filename>~/.psqlrc</filename> file before starting up.
@


1.244.2.2
log
@Spell and markup checking
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.244.2.1 2010/07/10 00:50:37 rhaas Exp $
d1037 1
a1037 1
        full description of each server is shown, including the
d1678 2
a1679 2
         class="parameter">text</>, can be specified.  (For multiword
         prompts, use single quotes.)
d2760 1
a2760 1
    (Note that this still won't work if <filename>my_file.txt</filename> contains NUL bytes.
@


1.243
log
@Add links to documentation sections in 9.0 release notes.

Also update tagging instructions, and add id tags to a few documentation
sections.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.242 2010/03/08 12:38:37 mha Exp $
d8 1
a8 1
    <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle>
d625 2
a626 2
    <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
    <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
d801 2
a802 2
        runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
        endterm="SQL-COPY-title"> command, but instead of the server
d813 2
a814 2
        <acronym>SQL</acronym> <xref linkend="sql-copy"
        endterm="sql-copy-title"> command.  Note that, because of this,
d982 1
a982 1
        linkend="sql-comment" endterm="sql-comment-title">
d1002 1
a1002 2
        The <xref linkend="sql-alterdefaultprivileges"
        endterm="sql-alterdefaultprivileges-title"> command is used to set
d1005 1
a1005 1
        <xref linkend="sql-grant" endterm="sql-grant-title">.
d1266 2
a1267 2
        The <xref linkend="sql-grant" endterm="sql-grant-title"> and
        <xref linkend="sql-revoke" endterm="sql-revoke-title">
d1270 1
a1270 1
        <xref linkend="sql-grant" endterm="sql-grant-title">.
d1289 2
a1290 2
        The <xref linkend="sql-alterrole" endterm="sql-alterrole-title"> and
        <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
d2099 1
a2099 1
        command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
@


1.242
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.241 2010/03/07 17:02:33 mha Exp $
d630 1
a630 1
  <refsect2>
@


1.241
log
@Revert patch for --psqlrc=FILENAME in psql.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.240 2010/03/06 15:28:09 mha Exp $
d730 1
a730 1
          To print your current working directory, use <literal>\!pwd</literal>.
@


1.240
log
@Add --psqlrc=FILENAME parameter to psql, to process an explicitly named
file instead of ~/.psqlrc on startup.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.239 2010/02/19 14:36:45 momjian Exp $
a483 10
    <varlistentry>
      <term><option>--psqlrc=<replaceable class="parameter">FILENAME</></></term>
      <listitem>
      <para>
      Read the start-up file from <replaceable class="parameter">FILENAME</>
      instead of <filename>~/.psqlrc</>.
      </para>
      </listitem>
    </varlistentry>

@


1.239
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/psql-ref.sgml,v 1.238 2010/02/19 03:50:03 momjian Exp $
d484 10
@


1.238
log
@First pass over client applications documentation proofreading.

gabrielle
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.237 2010/01/29 17:44:12 rhaas Exp $
d517 1
@


1.237
log
@Allow psql variables to be interpolated with literal or identifier escaping.

Loosely based on a patch by Pavel Stehule.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.236 2009/12/24 23:36:39 tgl Exp $
d57 1
a57 1
      useful for script processing rather than interactive mode. This is
d87 1
a87 1
      it contains no <application>psql</application> specific features),
d176 1
a176 1
      exactly the same output that you would have gotten had you entered
d288 1
a288 1
      space. Thus to set the output format to LaTeX, you could write
d526 2
a527 2
   finished normally, 1 if a fatal error of its own (out of memory,
   file not found) occurs, 2 if the connection to the server went bad
d544 1
a544 1
    database, the host name and port number of the server and what user
d551 1
a551 1
    these options are required; there are useful defaults. If you omit the host
d636 1
a636 1
    itself. These commands help make
d1730 1
a1730 1
          nicely formatted text output that is default.
d2192 1
a2192 1
        arguments are not further interpreted, the shell will see them
d2354 1
a2354 1
    the variable or represent some state of the application. Although
d2766 1
a2766 1
    changed unless the named variable is currently set. In any case you
@


1.236
log
@Try to improve the clarity of the psql documentation for the \d family of
commands, as per recent discussion.  Includes suggestions from Adrian Klaver
and Filip Rembialkowski.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.235 2009/11/25 20:26:30 tgl Exp $
d661 6
a666 1
    variable is used as the argument instead.
d2719 5
a2723 2
    them into regular <acronym>SQL</acronym> statements. The syntax for
    this is again to prepend the variable name with a colon
d2729 19
a2747 5
    would then query the table <literal>my_table</literal>. The value of
    the variable is copied literally, so it can even contain unbalanced
    quotes or backslash commands. You must make sure that it makes sense
    where you put it. Variable interpolation will not be performed into
    quoted <acronym>SQL</acronym> entities.
d2755 2
a2756 14
testdb=&gt; <userinput>\set content '''' `cat my_file.txt` ''''</userinput>
testdb=&gt; <userinput>INSERT INTO my_table VALUES (:content);</userinput>
</programlisting>
    One problem with this approach is that <filename>my_file.txt</filename>
    might contain single quotes. These need to be escaped so that
    they don't cause a syntax error when the second line is processed. This
    could be done with the program <command>sed</command>:
<programlisting>
testdb=&gt; <userinput>\set content '''' `sed -e "s/'/''/g" &lt; my_file.txt` ''''</userinput>
</programlisting>
    If you are using non-standard-conforming strings then you'll also need
    to double backslashes.  This is a bit tricky:
<programlisting>
testdb=&gt; <userinput>\set content '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' &lt; my_file.txt` ''''</userinput>
d2758 2
a2759 6
    Note the use of different shell quoting conventions so that neither
    the single quote marks nor the backslashes are special to the shell.
    Backslashes are still special to <command>sed</command>, however, so
    we need to double them.  (Perhaps
    at one point you thought it was great that all Unix commands use the
    same escape character.)
d2763 6
a2768 6
    Since colons can legally appear in SQL commands, the following rule
    applies: the character sequence
    <quote>:name</quote> is not changed unless <quote>name</> is the name
    of a variable that is currently set. In any case you can escape
    a colon with a backslash to protect it from substitution. (The
    colon syntax for variables is standard <acronym>SQL</acronym> for
d2772 3
a2774 1
    conflict.)
@


1.235
log
@Simplify psql's new linestyle behavior to default to linestyle=ascii all
the time, rather than hoping we can tell whether the terminal supports
UTF8 characters.  Per discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.234 2009/11/22 22:06:30 tgl Exp $
d638 1
a638 2
    scripting. Meta-commands are more commonly called slash or backslash
    commands.
d686 3
a688 2
    Parsing for arguments stops when another unquoted backslash occurs.
    This is taken as the beginning of a new meta-command. The special
d849 1
a849 1
        <term><literal>\d[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d855 7
a861 5
        columns, their types, the tablespace (if not the default) and any special
        attributes such as <literal>NOT NULL</literal> or defaults, if
        any. Associated indexes, constraints, rules, and triggers are
        also shown, as is the view definition if the relation is a view.
        (<quote>Matching the pattern</> is defined below.)
d868 1
a868 1
        table.
d882 1
a882 1
        all tables, views, and sequences. This is purely a convenience
d890 1
a890 1
        <term><literal>\da[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d894 1
a894 1
        Lists all available aggregate functions, together with their
d907 1
a907 1
        <term><literal>\db[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d911 1
a911 1
        Lists all available tablespaces. If <replaceable
d922 1
a922 1
        <term><literal>\dc[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d925 1
a925 1
        Lists all available conversions between character-set encodings.
d938 1
a938 1
        <term><literal>\dC [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d941 1
a941 1
        Lists all available type casts.
d951 1
a951 1
        <term><literal>\dd[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d984 1
a984 1
        <term><literal>\ddp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1007 1
a1007 1
        <term><literal>\dD[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1010 1
a1010 1
        Lists all available domains. If <replaceable
d1012 1
a1012 1
        is specified, only matching domains are shown.
d1022 1
a1022 1
        <term><literal>\des[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1025 1
a1025 1
        Lists all foreign servers (mnemonic: <quote>external
d1038 1
a1038 1
        <term><literal>\deu[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1041 1
a1041 1
        Lists all user mappings (mnemonic: <quote>external
d1061 1
a1061 1
        <term><literal>\dew[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1064 1
a1064 1
        Lists all foreign-data wrappers (mnemonic: <quote>external
d1077 1
a1077 1
        <term><literal>\df[antwS+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1081 7
a1087 5
        Lists available functions, together with their arguments,
        return types, and their function types: 'agg' (aggregate),
        'normal', 'trigger', and 'window'.  To display only functions
        of a specific type, use the corresponding letters <literal>a</>,
        <literal>n</>, <literal>t</>, or <literal>w</>.  If <replaceable
d1093 1
a1093 1
        objects are shown;  supply a pattern or the <literal>S</literal>
d1097 1
a1097 1
        <note>
d1100 2
a1101 2
        type, use your pager's search capability to scroll through the <literal>\df</>
        output.
d1103 1
a1103 1
        </note>
d1109 1
a1109 1
        <term><literal>\dF[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1112 1
a1112 1
         Lists available text search configurations.
d1123 1
a1123 1
        <term><literal>\dFd[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1126 1
a1126 1
         Lists available text search dictionaries.
d1137 1
a1137 1
        <term><literal>\dFp[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1140 1
a1140 1
         Lists available text search parsers.
d1151 1
a1151 1
        <term><literal>\dFt[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1154 1
a1154 1
         Lists available text search templates.
d1165 1
a1165 1
        <term><literal>\dg[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1168 1
a1168 1
        Lists all database roles. If <replaceable
d1180 4
a1183 4
        <term><literal>\di[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\ds[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dt[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dv[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1192 2
a1193 2
        these letters, in any order, to obtain a listing of all the
        matching objects.  For example, <literal>\dit</> lists indexes
d1197 3
a1199 1
        By default, only user-created objects are shown;  supply a
a1202 5

        <para>
        If <replaceable class="parameter">pattern</replaceable> is
        specified, only objects whose names match the pattern are listed.
        </para>
d1219 1
a1219 1
        <term><literal>\dn[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1223 2
a1224 2
        Lists available schemas (namespaces). If <replaceable
        class="parameter">pattern</replaceable> (a regular expression)
d1235 1
a1235 1
        <term><literal>\do[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1238 1
a1238 1
        Lists available operators with their operand and return types.
d1250 1
a1250 1
        <term><literal>\dp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1253 1
a1253 1
        Lists available tables, views and sequences with their
d1256 2
a1257 1
        specified, only tables, views and sequences whose names match the pattern are listed.
d1271 1
a1271 1
        <term><literal>\drds [ <replaceable class="parameter">role-pattern</replaceable> [ <replaceable class="parameter">database-pattern </replaceable> ] ]</literal></term>
d1274 7
a1280 6
        Lists defined configuration settings.  These settings can be role-specific,
        database-specific, or both.  <literal>role-pattern</literal> and
        <literal>database-pattern</literal> are used to select
        specific roles and database to list, respectively; if omitted, or * is specified,
        all settings are listed, including those not role-specific or database-specific,
        respectively.
d1286 2
a1287 1
        commands are used to define per-database role configuration settings.
d1293 1
a1293 1
        <term><literal>\dT[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1296 1
a1296 1
        Lists available data types.
d1311 1
a1311 1
        <term><literal>\du[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1314 1
a1314 1
        Lists all database roles. If <replaceable
d2139 2
a2140 1
        <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
d2163 1
a2163 1
        <term><literal>\z [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d2166 1
a2166 1
        Produces a list of all available tables, views and sequences with their
d2169 2
a2170 1
        specified, only tables,views and sequences whose names match the pattern are listed.
d2188 1
a2188 1
        as is.
d2234 14
d2251 1
a2251 1
   For example, <literal>\dt int*</> displays all tables whose names
a2292 8

  <para>
   Whenever the <replaceable class="parameter">pattern</replaceable> parameter
   is omitted completely, the <literal>\d</> commands display all objects
   that are visible in the current schema search path &mdash; this is
   equivalent to using the pattern <literal>*</>.
   To see all objects in the database, use the pattern <literal>*.*</>.
  </para>
@


1.234
log
@Assorted wordsmithing on the documentation of \pset --- try to make it
a bit more consistent and less obviously written by different people at
different times.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.233 2009/11/22 05:20:41 tgl Exp $
d1788 1
a1829 6

          <para>
          If this option has not been set, the default behavior is to use
          <literal>unicode</literal> style if the client character set encoding
          is UTF-8, otherwise <literal>ascii</literal> style.
          </para>
@


1.233
log
@Improve psql's tabular display of wrapped-around data by inserting markers
in the formerly-always-blank columns just to left and right of the data.
Different marking is used for a line break caused by a newline in the data
than for a straight wraparound.  A newline break is signaled by a "+" in the
right margin column in ASCII mode, or a carriage return arrow in UNICODE mode.
Wraparound is signaled by a dot in the right margin as well as the following
left margin in ASCII mode, or an ellipsis symbol in the same places in UNICODE
mode.  "\pset linestyle old-ascii" is added to make the previous behavior
available if anyone really wants it.

In passing, this commit also cleans up a few regression test files that
had unintended spacing differences from the current actual output.

Roger Leigh, reviewed by Gabrielle Roth and other members of PDXPUG.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.232 2009/10/13 21:04:01 tgl Exp $
d285 2
a286 2
      Allows you to specify printing options in the style of
      <command>\pset</command> on the command line. Note that here you
d369 1
a369 1
      Allows you to specify options to be placed within the
d1680 1
a1680 1
        <term><literal>\pset <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</literal></term>
d1684 10
a1693 5
        This command sets options affecting the output of query result
        tables. <replaceable class="parameter">parameter</replaceable>
        describes which option is to be set. The semantics of
        <replaceable class="parameter">value</replaceable> depend
        thereon.
d1712 1
a1712 1
          <quote>Unaligned</quote> writes all columns of a row on a
d1714 7
a1720 3
          is intended to create output that might be intended to be read
          in by other programs (tab-separated, comma-separated).
          <quote>Aligned</quote> mode is the standard, human-readable,
d1725 7
a1731 7
          <quote>Wrapped</quote> is like <literal>aligned</> but wraps
          output to the specified width.  If <literal>\pset columns</> is
          zero (the default), <literal>wrapped</> mode only affects screen
          output and wrapped width is controlled by the environment
          variable <envar>COLUMNS</> or the detected screen width.  If
          <literal>\pset columns</> is set to a non-zero value, all output
          is wrapped, including file and pipe output.
d1735 2
a1736 2
          The <quote><acronym>HTML</acronym></quote> and
          <quote>LaTeX</quote> modes put out tables that are intended to
d1749 10
a1758 4
          Controls the target width for the <literal>wrapped</> format,
          and width for determining if wide output requires the pager.
          Zero (the default) causes the <literal>wrapped</> format to
          affect only screen output.
d1767 2
a1768 1
          The second argument must be a number. In general, the higher
d1771 3
a1773 3
          <acronym>HTML</acronym> mode, this will translate directly
          into the <literal>border=...</literal> attribute, in the
          others only values 0 (no border), 1 (internal dividing lines),
d1788 2
d1796 4
a1799 4
          When the data wraps from one line
          to the next without a newline character, a dot (<literal>.</>)
          is shown in the right-hand margin of the first line, and
          again in the left-hand margin of the following line.
d1808 1
a1808 1
          When the data wraps from one line
d1816 1
a1816 1
          in the right-hand margin.  When the data wraps from one line
d1823 3
a1825 3
          When the selected output format is one that draws lines or boxes
          around the data, this setting also determines the characters
          with which the lines are drawn.
d1842 6
a1847 5
          You can specify an optional second argument, if it is provided it
          may be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable expanded mode.  If the second
          argument is not provided then we will toggle between regular and
          expanded format. When expanded format is enabled, query results
a1851 4

          <para>
          Expanded mode is supported by all four output formats.
          </para>
d1859 3
a1861 4
          The second argument is a string that should be printed
          whenever a column is null. The default is not to print
          anything, which can easily be mistaken for, say, an empty
          string. Thus, one might choose to write <literal>\pset null
d1872 1
a1872 1
          mode. That way one can create, for example, tab- or
d1885 6
a1890 5
          You can specify an optional second argument, if it is provided it
          may be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable display of the default footer
          <literal>(x rows)</literal>.  If the second argument is not
          provided then we will toggle between on and off.
d1899 6
a1904 6
          You can specify an optional second argument, if it is provided it
          may be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable display of a locale-aware character
          to separate groups of digits to the left of the decimal marker.  If
          the second argument is not provided then we will toggle between
          on and off.
d1914 1
a1914 1
          output mode. The default is a newline character.
d1923 7
a1929 6
          You can specify an optional second argument, if it is provided it
          may be either <literal>on</literal> or <literal>off</literal>
          which will enable or disable the tuples only mode.  If the
          second argument is not provided then we will toggle between tuples
          only and full display. Full display shows extra information such
          as column headers, titles, and various footers. In tuples only
d1936 1
a1936 1
          <term><literal>title [ <replaceable class="parameter">text</replaceable> ]</literal></term>
d1941 2
a1942 1
          argument is given, the title is unset.
d1948 1
a1948 1
          <term><literal>tableattr</literal> (or <literal>T</literal>) <literal>[ <replaceable class="parameter">text</replaceable> ]</literal></term>
d1951 3
a1953 2
          Allows you to specify any attributes to be placed inside the
          <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
d1958 3
a1964 1

d1969 1
a1969 1
          Controls use of a pager for query and <application>psql</>
d1977 3
a1979 2
          When the pager is <literal>off</>, the pager is not used. When the pager
          is <literal>on</>, the pager is used only when appropriate, i.e. the
d1981 5
a1985 3
          <literal>\pset pager</> turns the pager on and off. Pager can
          also be set to <literal>always</>, which causes the pager to be
          always used.
d1993 1
a1993 1
        Illustrations on how these different formats look can be seen in
d2008 2
a2009 2
        It is an error to call <command>\pset</command> without
        arguments. In the future this call might show the current status
d2118 3
a2120 3
        Allows you to specify attributes to be placed within the
        <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
        output mode. This command is equivalent to <literal>\pset
@


1.232
log
@Add "\pset linestyle ascii/unicode" option to psql, allowing our traditional
ASCII-art style of table output to be upgraded to use Unicode box drawing
characters if desired.  By default, psql will use the Unicode characters
whenever client_encoding is UTF8.

The patch forces linestyle=ascii in pg_regress usage, ensuring we don't
break the regression tests in Unicode locales.

Roger Leigh
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.231 2009/10/08 16:34:00 alvherre Exp $
d1768 2
a1769 1
          of <literal>ascii</literal> or <literal>unicode</literal>.
d1775 7
a1781 1
          <quote>ASCII</quote> uses plain <acronym>ASCII</acronym> characters.
d1785 17
a1801 1
          <quote>Unicode</quote> uses Unicode box-drawing characters.
d1806 2
a1807 1
          around the data, this setting controls how the lines are drawn.
d1813 3
a1815 3
          If this option has not been set, the default behavior is to
          use Unicode characters if the client character set encoding
          is UTF-8, otherwise <acronym>ASCII</acronym> characters.
@


1.231
log
@Add the new psql command \drds to the psql docs, help and tab completion.

I also thank Bernd Helmle for the documentation help on the previous settings
patch, which I forgot on the commit message.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.230 2009/10/05 19:24:34 tgl Exp $
d1764 33
@


1.230
log
@Create an ALTER DEFAULT PRIVILEGES command, which allows users to adjust
the privileges that will be applied to subsequently-created objects.

Such adjustments are always per owning role, and can be restricted to objects
created in particular schemas too.  A notable benefit is that users can
override the traditional default privilege settings, eg, the PUBLIC EXECUTE
privilege traditionally granted by default for functions.

Petr Jelinek
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.229 2009/08/11 12:02:58 momjian Exp $
d1268 19
@


1.229
log
@Remove tab in SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.228 2009/08/10 02:39:04 adunstan Exp $
d982 23
d1168 2
a1169 2
        If the form <literal>\dg+</literal> is used, additional information 
        is shown about each role, including the comment for each role.  
d1261 3
a1263 1
        commands are used to set access privileges.
a2073 6
        The <xref linkend="sql-grant" endterm="sql-grant-title"> and
        <xref linkend="sql-revoke" endterm="sql-revoke-title">
        commands are used to set access privileges.
        </para>

        <para>
@


1.228
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.227 2009/07/25 17:04:19 tgl Exp $
d243 1
a243 1
	<varlistentry>
@


1.227
log
@Code review for FORCE QUOTE * patch: fix error checking to consider FORCE
QUOTE * as a variety of FORCE QUOTE, and update psql documentation to include
the option.  (The actual psql code doesn't seem to need any changes.)
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.226 2009/07/24 19:35:44 petere Exp $
d243 11
@


1.226
log
@Document \dg+ and \du+

The fact that \dg and \du take the + option was missing in the documentation.

backpatched to 8.4

Author: Andreas Wenk <a.wenk@@netzmeister-st-pauli.de>
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225 2009/04/21 17:23:05 momjian Exp $
d777 1
a777 1
              [ force quote <replaceable class="parameter">column_list</replaceable> ]
@


1.225
log
@Merge psql \df options into a single \? line, and update docs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.224 2009/04/21 15:49:06 momjian Exp $
d1127 1
a1127 1
        <term><literal>\dg [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1133 3
a1135 1
        (This command is now effectively the same as <literal>\du</>.)
d1252 1
a1252 1
        <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1258 2
@


1.225.2.1
log
@Document \dg+ and \du+

The fact that \dg and \du take the + option was missing in the documentation.

backpatched to 8.4

Author: Andreas Wenk <a.wenk@@netzmeister-st-pauli.de>
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225 2009/04/21 17:23:05 momjian Exp $
d1127 1
a1127 1
        <term><literal>\dg[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1133 1
a1133 3
        (This command is now effectively the same as <literal>\du</literal>).
        If the form <literal>\dg+</literal> is used, additional information 
        is shown about each role, including the comment for each role.  
d1250 1
a1250 1
        <term><literal>\du[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
a1255 2
        If the form <literal>\du+</literal> is used, additional information
        is shown about each role, including the comment for each role.
@


1.225.2.2
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225.2.1 2009/07/24 19:35:26 petere Exp $
a242 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.225.2.3
log
@Remove tab in SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225.2.2 2009/08/10 02:50:18 adunstan Exp $
d243 1
a243 1
    <varlistentry>
@


1.225.2.4
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225.2.3 2009/08/15 19:33:29 momjian Exp $
d724 1
a724 1
          To print your current working directory, use <literal>\! pwd</literal>.
@


1.225.2.5
log
@Backpatch some blatant spelling mistakes
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.225.2.4 2010/03/08 12:39:51 mha Exp $
d1005 1
a1005 1
        full description of each server is shown, including the
@


1.224
log
@Add agg/normal/trigger/window flags for psql \df and in \df output.

David Fetter
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.223 2009/04/08 22:29:30 tgl Exp $
d1041 1
a1041 2
        <term><literal>\df[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\df[antw][S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
@


1.223
log
@Remove psql's ancient hack that suppressed functions taking or returning
cstring from the output of \df.  Now that the default behavior is to
exclude all system functions, the de-cluttering rationale for this behavior
seems pretty weak; and it was always quite confusing/unhelpful if you were
actually looking for I/O functions.  (Not to mention if you were looking
for encoding converters or other cases that might take or return cstring.)
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.222 2009/04/04 00:39:14 tgl Exp $
d1042 1
d1046 12
a1057 9
        Lists available functions, together with their argument and
        return types. If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only functions whose names match the pattern are shown.
        If the form <literal>\df+</literal> is used, additional information about
        each function, including volatility, language, source code and description, is shown.
        By default, only user-created objects are shown;  supply a
        pattern or the <literal>S</literal> modifier to include system
        objects.
a1070 1

@


1.222
log
@Minor wordsmithing on descriptions of some \d commands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.221 2009/04/02 15:15:31 momjian Exp $
d1058 1
a1058 1
        To look up functions taking argument or returning values of a specific
a1061 6

        <para>
        To reduce clutter, <literal>\df</> does not show data type I/O
        functions.  This is implemented by ignoring functions that accept
        or return type <type>cstring</>.
        </para>
@


1.221
log
@Change psql \d* display so 'S' _or_ a pattern include system objects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.220 2009/02/26 16:02:37 petere Exp $
d856 3
d948 3
a950 3
        (<quote>Object</quote> covers aggregates, functions, operators,
        types, relations (tables, views, indexes, sequences, large
        objects), rules, and triggers.) For example:
d1190 1
a1190 1
        Lists all available schemas (namespaces). If <replaceable
d1220 1
a1220 1
        Produces a list of all available tables, views and sequences with their
d1239 6
a1244 4
        Lists all data types or only those that match <replaceable
        class="parameter">pattern</replaceable>. The command form
        <literal>\dT+</literal> shows extra information, namely the type's internal name, size, and
        allowed values for <type>enum</> types.
d1257 3
a1259 2
        Lists all database roles, or only those that match <replaceable
        class="parameter">pattern</replaceable>.
@


1.220
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/psql-ref.sgml,v 1.219 2009/02/09 14:09:56 momjian Exp $
d856 3
a858 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d882 3
a884 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d913 3
a915 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d942 3
a944 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d974 3
a976 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d1048 3
a1050 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d1158 3
a1160 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d1205 3
a1207 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
d1240 3
a1242 3
        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
@


1.219
log
@Fix spelling error in docs.

Erik Rijkers
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.218 2009/01/20 02:38:37 momjian Exp $
d405 20
@


1.218
log
@Update \d*S documentation to be more accurate;  system objects are added
to the display, not restricted in the display; new text:

        The letter <literal>S</literal> adds the listing of system
        objects; without <literal>S</literal>, only non-system
        objects are shown.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.217 2009/01/09 19:27:14 tgl Exp $
d1749 1
a1749 1
          to seperate groups of digits to the left of the decimal marker.  If
@


1.217
log
@A further attempt at clarifying the \distv business.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.216 2009/01/07 04:51:34 momjian Exp $
d836 3
a838 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
d862 3
a864 3
        The letter <literal>S</literal> restricts the listing
        to system objects; without <literal>S</literal>, only
        non-system objects are shown.
d893 3
a895 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
d922 3
a924 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
d954 3
a956 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
d1028 3
a1030 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
d1138 3
a1140 3
        The letter <literal>S</literal> restricts the listing
        to system objects; without <literal>S</literal>, only
        non-system objects are shown.
d1185 3
a1187 3
        The letter <literal>S</literal> restricts the listing
        to system objects; without <literal>S</literal>, only
        non-system objects are shown.
d1220 3
a1222 2
        The letter <literal>S</literal> restricts the listing to system objects; without
        <literal>S</literal>, only non-system objects are shown.
@


1.216
log
@Break out \distv into four separate lines in the psql documentation, for
clarity.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.215 2009/01/06 23:01:57 momjian Exp $
d1123 1
a1123 1
        For the above commands, the letters
d1125 3
a1127 3
        <literal>t</literal>, <literal>v</literal>,
        <literal>S</literal> stand for index, sequence, table, view,
        and system table, respectively. You can specify any or all of
d1129 2
a1130 1
        matching objects.  If <literal>+</literal> is
@


1.215
log
@Add documentation for new \d*S* patch, and clean up some of the docs.
Fix \do and trigger display for the patch too.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.214 2008/12/19 16:25:16 petere Exp $
d1116 4
a1119 1
        <term><literal>\distv[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1123 1
a1123 1
        This is not the actual command name: the letters
@


1.214
log
@SQL/MED catalog manipulation facilities

This doesn't do any remote or external things yet, but it gives modules
like plproxy and dblink a standardized and future-proof system for
managing their connection information.

Martin Pihlak and Peter Eisentraut
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.213 2008/12/01 09:20:37 petere Exp $
d818 1
a818 2
        <term><literal>\d [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\d+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d836 2
d853 1
a853 1
        <term><literal>\da [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d861 3
d870 1
a870 2
        <term><literal>\db [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\db+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d885 1
a885 1
        <term><literal>\dc [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d892 2
d913 1
a913 1
        <term><literal>\dd [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d920 2
d945 1
a945 1
        <term><literal>\dD [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d951 2
d959 1
a959 2
        <term><literal>\des [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\des+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d975 1
a975 2
        <term><literal>\deu [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\deu+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d998 1
a998 2
        <term><literal>\dew [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dew+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1014 1
a1014 2
        <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\df+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1024 2
d1047 1
a1047 2
        <term><literal>\dF [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dF+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1061 1
a1061 2
        <term><literal>\dFd [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dFd+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1075 1
a1075 2
        <term><literal>\dFp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dFp+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1089 1
a1089 2
        <term><literal>\dFt [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dFt+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1116 1
a1116 1
        <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1126 1
a1126 3
        matching objects.  The letter <literal>S</literal> restricts
        the listing to system objects; without <literal>S</literal>,
        only non-system objects are shown.  If <literal>+</literal> is
d1129 3
d1154 1
a1154 2
        <term><literal>\dn [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dn+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1170 1
a1170 1
        <term><literal>\do [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1176 3
d1204 1
a1204 2
        <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
        <term><literal>\dT+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d1211 2
@


1.213
log
@Small correction
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.212 2008/11/06 15:18:35 tgl Exp $
d950 58
@


1.212
log
@Improve psql's \dC command to take a pattern parameter.  Casts are shown
if their source or target types match the pattern (using the same definition
of "match" as \dT does).  Per recent discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.211 2008/09/06 20:18:08 tgl Exp $
a576 2
test=>

@


1.211
log
@Adjust psql's new \ef command to present an empty CREATE FUNCTION template
for editing if no function name is specified.  This seems a much cleaner way
to offer that functionality than the original patch had.  In passing,
de-clutter the error displays that are given for a bogus function-name
argument, and standardize on "$function$" as the default delimiter for the
function body.  (The original coding would use the shortest possible
dollar-quote delimiter, which seems to create unnecessarily high risk of
later conflicts with the user-modified function body.)
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.210 2008/09/06 00:01:21 tgl Exp $
d897 1
a897 1
        <term><literal>\dC</literal></term>
d901 3
@


1.210
log
@Implement a psql command "\ef" to edit the definition of a function.
In support of that, create a backend function pg_get_functiondef().
The psql command is functional but maybe a bit rough around the edges...

Abhijit Menon-Sen
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.209 2008/07/03 03:37:16 tgl Exp $
d1164 1
a1164 1
        <term><literal>\edit</literal> (or <literal>\e</literal>) <literal>[ <replaceable class="parameter">filename</replaceable> ]</literal></term>
d1199 1
a1199 1
        <term><literal>\ef <replaceable class="parameter">function_description</replaceable> </literal></term>
d1217 5
@


1.209
log
@Fix psql's \d and allied commands to work with all server versions back to 7.4.
Guillaume Lelarge, with some additional fixes by me.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.208 2008/06/11 10:48:16 heikki Exp $
d1199 23
@


1.208
log
@Add optional on/off argument to \timing.

David Fetter.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.207 2008/06/01 16:23:08 tgl Exp $
d410 1
a410 1
       password before connecting to a database.  
d462 1
a462 1
        complete successfully, or no changes are applied.  
d545 2
a546 2
     <parameter>conninfo</parameter> string, which is used instead of a 
     database name. This mechanism give you very wide control over the 
d876 1
a876 1
        If <literal>+</literal> is appended to the command name, each object 
d1514 1
a1514 1
          <literal>aligned</literal>, <literal>wrapped</literal>, 
d2536 1
a2536 1
          <literal>[local:<replaceable>/dir/name</replaceable>]</literal>, 
d2860 5
a2864 12
      In an earlier life <application>psql</application> allowed the
      first argument of a single-letter backslash command to start
      directly after the command, without intervening whitespace. For
      compatibility this is still supported to some extent,
      but we are not going to explain the details here as this use is
      discouraged.  If you get strange messages, keep this in mind.
      For example:
<programlisting>
testdb=&gt; <userinput>\foo</userinput>
Field separator is "oo".
</programlisting>
      which is perhaps not what one would expect.
d2870 8
a2877 5
      <application>psql</application> only works smoothly with servers
      of the same version. That does not mean other combinations will
      fail outright, but subtle and not-so-subtle problems might come
      up.  Backslash commands are particularly likely to fail if the
      server is of a different version.
@


1.207
log
@Marginal improvements to the documentation for PGOPTIONS.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.206 2008/05/16 17:17:00 momjian Exp $
d1864 1
a1864 1
       <term><literal>\timing</literal></term>
d1867 2
a1868 1
         Toggles a display of how long each SQL statement takes, in milliseconds.
@


1.206
log
@Update psql startup banner to be shorter, suggest "help" for help.

Add a few "help" entries.

Move \g help entry into "General".

Update psql version mismatch warning text.

Joshua D. Drake
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.205 2008/05/16 16:59:05 momjian Exp $
a2756 9

    <listitem>
     <para>
      Default connection database
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
d2763 1
a2763 1
      Default connection parameters
@


1.205
log
@Add detection of psql pager to trigger on wide output.  Also add pager
detection for wrapped lines or lines with newlines that need pager to
display.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.204 2008/05/14 04:07:01 momjian Exp $
d574 2
a575 1
Welcome to psql &version;, the PostgreSQL interactive terminal.
d577 1
a577 5
Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit
@


1.204
log
@Remove odd duplicate wording in psql pager section.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.203 2008/05/08 17:04:26 momjian Exp $
d1558 2
a1559 1
          Controls the target width for the <literal>wrapped</> format.
d1721 3
a1723 4
          (<application>psql</> does not do a perfect job of estimating
          when to use the pager.) <literal>\pset pager</> turns the
          pager on and off. Pager can also be set to <literal>always</>,
          which causes the pager to be always used.
d2737 3
a2739 2
      Used for the <literal>wrapped</> output format if 
      <literal>\pset columns</> is zero.
@


1.203
log
@Add psql '\pset format wrapped' mode to wrap output to screen width, or
file/pipe output too if \pset columns' is set.

Bryce Nesbitt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.202 2008/05/08 00:27:57 momjian Exp $
d1717 2
a1718 2
          When the pager is off, the pager is not used. When the pager
          is on, the pager is used only when appropriate, i.e. the
d1723 1
a1723 4
          which causes the pager to be always used, or you can set the pager
          to <literal>on</> which will enable the usage of the pager when
          appropriate, or you can set the pager to <literal>off</> which
          will disable the pager.
@


1.202
log
@Remove OID/foreign key mention in psql variable interpolation docs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.201 2008/05/05 01:38:08 adunstan Exp $
d1517 2
a1518 1
          <literal>aligned</literal>, <literal>html</literal>,
d1530 15
a1544 2
          nicely formatted text output that is default. The
          <quote><acronym>HTML</acronym></quote> and
d1555 11
d2734 12
@


1.201
log
@Document extra information provided by psql's \dT+ (not \dt+ as per recent commit).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.200 2008/05/02 22:50:21 tgl Exp $
d2443 1
a2443 3
    A popular application of this facility is to refer to the last
    inserted <acronym>OID</acronym> in subsequent statements to build a
    foreign key scenario. Another possible use of this mechanism is to
@


1.200
log
@Update documentation for psql relation-size-in-\dt+ patch.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.199 2008/03/30 18:10:20 tgl Exp $
d1148 2
a1149 1
        <literal>\dT+</literal> shows extra information.
@


1.199
log
@Show database access privileges in psql's \l command.  For \l+, also show
database size, when available to the current user.

Andrew Gilligan
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.198 2007/12/11 19:57:32 tgl Exp $
d1071 1
a1071 1
        associated description, if any.
@


1.198
log
@Make documentation of -W options more accurate and uniform.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.197 2007/12/11 19:01:06 tgl Exp $
d1331 6
a1336 3
        List the names, owners, and character set encodings of all the databases in
        the server. If <literal>+</literal> is appended to the command
        name, database descriptions are also displayed.
@


1.198.2.1
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.198 2007/12/11 19:57:32 tgl Exp $
a242 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.198.2.2
log
@Remove tabs from SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.198.2.1 2009/08/10 02:39:24 adunstan Exp $
d243 1
a243 1
    <varlistentry>
@


1.198.2.3
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.198.2.2 2009/08/15 20:23:20 momjian Exp $
d709 1
a709 1
          To print your current working directory, use <literal>\! pwd</literal>.
@


1.197
log
@Remove the long-deprecated -u option from psql, since it does nothing very
useful and confuses people who think it is the same as -U.  (Eventually
we might want to re-introduce it as being an alias for -U, but that should
not happen until the switch has actually not been there for a few releases.)
Likewise in pg_dump and pg_restore.  Per gripe from Robert Treat and
subsequent discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.196 2007/10/29 17:29:59 momjian Exp $
d409 2
a410 2
      Forces <application>psql</application> to prompt for a
      password before connecting to a database.  
d414 6
a419 6
      <application>psql</application> should automatically prompt for a
      password whenever the server requests password authentication.
      However, currently password request detection is not totally
      reliable, hence this option to force a prompt. If no password
      prompt is issued and the server requires password authentication,
      the connection attempt will fail.
d423 3
a425 3
      This option will remain set for the entire session, even if you
      change the database connection with the meta-command
      <command>\connect</command>.
a426 1

@


1.196
log
@Documentation wording fixes.

Guillaume Lelarge
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.195 2007/09/14 14:31:22 momjian Exp $
a365 18
      <term><option>-u</></term>
      <listitem>
      <para>
      Forces <application>psql</application> to prompt for the user name and
      password before connecting to the database.
      </para>

      <para>
      This option is deprecated, as it is conceptually flawed.
      (Prompting for a non-default user name and prompting for a
      password because the server requires it are really two different
      things.) You are encouraged to look at the <option>-U</option> and
      <option>-W</option> options instead.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
@


1.195
log
@Add LDAP URL documentation.

Albe Laurenz
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.194 2007/08/22 04:45:20 tgl Exp $
d1660 1
a1660 1
          which will enable or display the tuples only mode.  If the
@


1.194
log
@Text search doc updates --- first cut at
syncing the existing docs with the final syntax decisions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.193 2007/07/10 00:21:31 tgl Exp $
d570 2
@


1.193
log
@Adjust processSQLNamePattern() so that $ within the pattern is always matched
literally, whether quoted or not.  Since we allow $ as a character within
identifiers, this behavior is useful, whereas the previous behavior of
treating it as the regexp ending anchor was nearly useless given that the
pattern is automatically anchored anyway.  This affects the arguments of
psql's \d commands as well as pg_dump's -n and -t switches.  Per discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.192 2007/06/28 06:40:16 neilc Exp $
d1001 60
@


1.192
log
@Add the function's volatility to the output of psql's \df+ command.
Update the psql reference page accordingly.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.191 2007/05/03 15:47:48 alvherre Exp $
d1919 2
a1920 2
   <literal>\dt foo*.bar*</> displays all tables whose table name
   starts with <literal>bar</> that are in schemas whose schema name
d1933 3
a1935 2
   translated to the regular-expression notation <literal>.*</>, and
   <literal>?</> which is translated to <literal>.</>.  You can emulate
d1942 5
a1946 3
   Remember that the pattern must match the whole name, unlike the usual
   interpretation of regular expressions; write <literal>*</> at the beginning
   and/or end if you don't wish the pattern to be anchored.
@


1.191
log
@Fix a few more double words in docs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.190 2007/03/26 17:23:37 tgl Exp $
d979 1
a979 1
        each function, including language and description, is shown.
@


1.190
log
@Fix seriously broken markup for libpq-envars cross-references.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.189 2007/03/16 08:28:01 mha Exp $
d117 1
a117 1
       If this parameter contains an <symbol>=</symbol> sign, it it treated as a
@


1.189
log
@Show aggregate return types in psql \da output.

Greg Sabino Mullane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.188 2007/03/03 17:19:11 momjian Exp $
d2734 2
a2735 2
   also uses the environment variables supported by <xref 
   linkend="libpq-envars" endterm="libpq">.
@


1.188
log
@Allow \pset and \x, \t to use boolean constants on/off, rather than just
toggle.

Chad Wagner
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.187 2007/02/23 18:20:58 momjian Exp $
d878 2
a879 2
        Lists all available aggregate functions, together with the data
        types they operate on. If <replaceable
@


1.187
log
@Add psql \prompt capability.

Chad Wagner
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.186 2007/02/21 23:22:42 momjian Exp $
d1512 8
a1519 5
          Toggles between regular and expanded format. When expanded
          format is enabled, query results are displayed in two
          columns, with the column name on the left and the data on
          the right. This mode is useful if the data wouldn't fit on the
          screen in the normal <quote>horizontal</quote> mode.
d1559 5
a1563 2
          Toggles the display of the default footer <literal>(x
          rows)</literal>.
d1572 6
a1577 3
          Toggles the display of a locale-aware character to separate groups
          of digits to the left of the decimal marker.  It also enables
          a locale-aware decimal marker.
d1596 7
a1602 4
          Toggles between tuples only and full display. Full display
          shows extra information such as column headers, titles, and
          various footers. In tuples only mode, only actual table data
          is shown.
d1651 4
a1654 1
          which causes the pager to be always used.
@


1.186
log
@Remove extra tab.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.185 2007/02/21 23:21:12 momjian Exp $
d1433 18
@


1.185
log
@Remove tabs from SGML reference files, so their addition can be detected
in the future.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.184 2007/02/20 18:10:58 momjian Exp $
d564 1
a564 1
     <parameter>conninfo</parameter>	string, which is used instead of a 
@


1.184
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/psql-ref.sgml,v 1.183 2007/02/01 19:10:24 momjian Exp $
d111 9
a119 9
      Specifies the name of the database to connect to. This is
      equivalent to specifying <replaceable
      class="parameter">dbname</replaceable> as the first non-option
      argument on the command line.
      </para>
	  <para>
	  If this parameter contains an <symbol>=</symbol> sign, it it treated as a
	  <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
	  </para>
d562 5
a566 5
	<para>
    An alternative way to specify connection parameters is in a
	<parameter>conninfo</parameter>	string, which is used instead of a 
	database name. This mechanism give you very wide control over the 
	connection. For example:
d570 3
a572 3
    See <xref linkend="libpq-connect"> for more information on all the
	available connection options.
	</para>
@


1.183
log
@Wording cleanup for error messages.  Also change can't -> cannot.

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/psql-ref.sgml,v 1.182 2007/02/01 00:28:19 momjian Exp $
d2700 3
a2702 4
   Because <application>psql</application> uses <application>libpq</application>
   internally, all <application>libpq</application> environment variables are
   also honored by <application>psql</application>.  For a complete list of those
   variables, see <xref linkend="libpq-envars">.
@


1.182
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.181 2007/01/31 23:26:04 momjian Exp $
d546 1
a546 1
    Unix user name, as is the default database name. Note that you can't
@


1.181
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/psql-ref.sgml,v 1.180 2007/01/20 16:57:31 neilc Exp $
d566 1
a566 1
	connection. For example,
d588 1
a588 1
    the string <literal>=&gt;</literal>. For example,
d2137 1
a2137 1
        value is <filename>~/.psql_history</filename>.  For example, putting
d2347 1
a2347 1
    (<literal>:</literal>).
d2364 1
a2364 1
    variable and then proceed as above.
d2569 1
a2569 1
         the prompt.  For example,
d2762 1
a2762 1
      For example
@


1.180
log
@Teach psql's \lo slash commands to respect quiet mode, and to output
HTML in HTML mode. Patch from Jeremy Drake.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.179 2006/12/19 01:53:36 adunstan Exp $
d604 1
a604 1
    At the prompt, the user may type in <acronym>SQL</acronym> commands.
d641 1
a641 1
    To include whitespace into an argument you may quote it with a
d822 1
a822 1
        amounts of data the <acronym>SQL</acronym> command may be preferable.
d1175 1
a1175 1
        query output you may wish to use <command>\qecho</command>
d1569 2
a1570 2
          Toggles between tuples only and full display. Full display may
          show extra information such as column headers, titles, and
d2025 1
a2025 1
         prefer autocommit-off, you may wish to set it in the system-wide
d2096 1
a2096 1
        Keep in mind that when using this feature, a query may
d2390 1
a2390 1
    Since colons may legally appear in SQL commands, the following rule
d2562 1
a2562 1
         Prompts may contain terminal control characters which, for
d2568 1
a2568 1
         <literal>%]</literal>. Multiple pairs of these may occur within
@


1.179
log
@Interpret a dbName param to PQsetdbLogin as a conninfo string if it contains an = sign. Tom Lane and Andrew Dunstan.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.178 2006/12/06 15:47:22 momjian Exp $
d1332 6
a1337 5
        The response indicates that the large object received object ID
        152801 which one ought to remember if one wants to access the
        object ever again. For that reason it is recommended to always
        associate a human-readable comment with every object. Those can
        then be seen with the <command>\lo_list</command> command.
@


1.178
log
@Change psql \\ example to use single quotes, per TOm.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.177 2006/12/06 15:40:11 momjian Exp $
d116 4
d562 12
@


1.177
log
@Clean up psql -c documentation that uses \\.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.176 2006/12/05 17:40:55 momjian Exp $
d92 1
a92 1
      this: <literal>echo "\x \\ SELECT * FROM foo;" | psql</literal>.
@


1.176
log
@Fix documentation example of using psql \x with a SELECT command, per
Simon Riggs.  Backpatch to 8.2.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175 2006/11/21 17:01:58 momjian Exp $
d90 4
a93 3
      meta-commands. To achieve that, you could pipe the string into
      <application>psql</application>, like this: <literal>echo -e
      "\\x\nSELECT * FROM foo;" | psql</literal>.
@


1.175
log
@Move libpq environment reference in psql documentation to a more
appropriate place, per Andrew Dunstan.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.174 2006/10/31 02:29:15 tgl Exp $
d91 2
a92 2
      <application>psql</application>, like this: <literal>echo "\x \\
      select * from foo;" | psql</literal>.
@


1.175.2.1
log
@Fix documentation example of using psql \x with a SELECT command, per
Simon Riggs.  Backpatch to 8.2.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175 2006/11/21 17:01:58 momjian Exp $
d91 2
a92 2
      <application>psql</application>, like this: <literal>echo -e
      "\\x\nSELECT * FROM foo;" | psql</literal>.
@


1.175.2.2
log
@Clean up psql -c documentation that uses \\.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175.2.1 2006/12/05 17:41:02 momjian Exp $
d90 3
a92 4
      meta-commands with this option. To achieve that, you could
      pipe the string into <application>psql</application>, like
      this: <literal>echo "\x \\ SELECT * FROM foo;" | psql</literal>.
      (<literal>\\</> is the separator meta-command.)
@


1.175.2.3
log
@Backpatch FAQ entry for null concatenation.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175.2.2 2006/12/06 15:40:32 momjian Exp $
d92 1
a92 1
      this: <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
@


1.175.2.4
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/psql-ref.sgml,v 1.175.2.3 2006/12/11 22:48:08 momjian Exp $
d2683 4
a2686 3
   This utility, like most other <productname>PostgreSQL</> utilities,
   also uses the environment variables supported by <xref 
   linkend="libpq-envars" endterm="libpq">.
@


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


1.175.2.6
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175.2.5 2007/03/26 17:23:45 tgl Exp $
a238 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.175.2.7
log
@Remove tabs from SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175.2.6 2009/08/10 02:39:20 adunstan Exp $
d239 1
a239 1
    <varlistentry>
@


1.175.2.8
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.175.2.7 2009/08/15 20:23:09 momjian Exp $
d710 1
a710 1
          To print your current working directory, use <literal>\! pwd</literal>.
@


1.174
log
@Fix misstatement about the results of using -1 with BEGIN.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.173 2006/10/31 01:52:31 neilc Exp $
d2680 8
a2906 8
 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member>Environment Variables (<xref linkend="libpq-envars">)</member>
  </simplelist>
 </refsect1>

@


1.173
log
@Add text to the VACUUM, REINDEX, DROP TABLESPACE and CREATE TABLESPACE
reference pages documenting that these commands cannot be used within
a transaction block. Also make some minor improvements to the psql
reference page. Patch from Simon Riggs, minor editorialization by
myself.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.172 2006/10/23 18:10:32 petere Exp $
d480 6
a485 4
        If the script itself uses <command>BEGIN</>, <command>COMMIT</>
        or any command that cannot be executed inside a transaction
        block, specifying this option will cause the transaction to be
        aborted.
@


1.172
log
@Spellchecking and such
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.171 2006/10/09 23:31:29 tgl Exp $
d97 4
a100 3
       BEGIN/COMMIT commands included in the string to divide it into
       multiple transactions.  This is different from the behavior when
       the same string is fed to <application>psql</application>'s standard input.
d476 8
a483 3
        complete successfully, or no changes are applied.  (However, if the
        script itself uses <command>BEGIN</> or <command>COMMIT</>, this
        option will not have the desired effect!)
@


1.171
log
@Improve description of the pattern matching rules used by psql's \d
commands (and soon by pg_dump).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.170 2006/10/03 21:14:46 momjian Exp $
d2775 1
a2775 1
      Set the console font to <quote>Lucida Console</>, because the
@


1.170
log
@Improve readline psql prompt suggestion.

Andreas Seltenreich
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.169 2006/09/16 00:30:19 momjian Exp $
d1820 8
d1831 24
a1854 8
   object name(s) to be displayed.  <literal>*</> means <quote>any
   sequence of characters</> and <literal>?</> means <quote>any single
   character</>.  (This notation is comparable to Unix shell file name
   patterns.)  Advanced users can also use regular-expression
   notations such as character classes, for example <literal>[0-9]</>
   to match <quote>any digit</>.  To make any of these
   pattern-matching characters be interpreted literally, surround it
   with double quotes.
d1858 1
a1858 1
   A pattern that contains an (unquoted) dot is interpreted as a schema
d1860 3
a1862 3
   <literal>\dt foo*.bar*</> displays all tables in schemas whose name
   starts with <literal>foo</> and whose table name
   starts with <literal>bar</>.  If no dot appears, then the pattern
d1864 25
d1894 3
a1896 2
   that are visible in the current schema search path.  To see all objects
   in the database, use the pattern <literal>*.*</>.
d1898 1
@


1.169
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.168 2006/08/30 23:34:21 tgl Exp $
d2494 1
a2494 1
testdb=&gt; \set PROMPT1 '%[%033[1;33;40m%]%n@@%/%R%[%033[0m%#%] '
@


1.168
log
@Extend COPY to support COPY (SELECT ...) TO ...

Bernd Helmle
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.167 2006/08/29 22:25:04 tgl Exp $
a2848 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.167
log
@Create a FETCH_COUNT parameter that causes psql to execute SELECT-like
queries via a cursor, fetching a limited number of rows at a time and
therefore not risking exhausting memory.  A disadvantage of the scheme
is that 'aligned' output mode will align each group of rows independently
leading to odd-looking output, but all the other output formats work
reasonably well.  Chris Mair, with some additional hacking by moi.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.166 2006/07/27 19:52:04 tgl Exp $
d742 1
a742 2
        <term><literal>\copy <replaceable class="parameter">table</replaceable>
        [ ( <replaceable class="parameter">column_list</replaceable> ) ]
d781 1
a781 3
        <literal>\copy <replaceable
        class="parameter">table</replaceable> from <replaceable
        class="parameter">stdin | stdout</replaceable></literal>
@


1.166
log
@Aggregate functions now support multiple input arguments.  I also took
the opportunity to treat COUNT(*) as a zero-argument aggregate instead
of the old hack that equated it to COUNT(1); this is materially cleaner
(no more weird ANYOID cases) and ought to be at least a tiny bit faster.
Original patch by Sergey Koposov; review, documentation, simple regression
tests, pg_dump and psql support by moi.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.165 2006/05/31 22:34:35 tgl Exp $
d2011 27
@


1.165
log
@Fix example of how to escape data in psql backslash commands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.164 2006/05/31 11:47:20 momjian Exp $
d857 1
a857 1
        type they operate on. If <replaceable
@


1.164
log
@Recommend '' for literal ', rather than \', in psql documentation.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.163 2006/05/31 11:35:17 momjian Exp $
d2268 1
a2268 1
    One possible problem with this approach is that <filename>my_file.txt</filename>
d2273 1
a2273 1
testdb=&gt; <userinput>\set content '''' `sed -e "s/'/\\\\''/g" &lt; my_file.txt` ''''</userinput>
d2275 9
a2283 8
    Observe the correct number of backslashes (6)! It works
    this way: After <application>psql</application> has parsed this
    line, it passes <literal>sed -e "s/'/\\''/g" &lt; my_file.txt</literal>
    to the shell. The shell will do its own thing inside the double
    quotes and execute <command>sed</command> with the arguments
    <literal>-e</literal> and <literal>s/'/''/g</literal>. When
    <command>sed</command> parses this it will replace the two
    backslashes with a single one and then do the substitution. Perhaps
d2285 1
a2285 5
    same escape character. And this is ignoring the fact that you might
    have to escape all backslashes as well because
    <acronym>SQL</acronym> text constants are also subject to certain
    interpretations. In that case you might be better off preparing the
    file externally.
@


1.163
log
@Support '' for literal ' in psql single-quote strings, documentation update.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.162 2006/05/26 19:51:29 tgl Exp $
d618 1
a618 1
    precede it by a backslash. Anything contained in single quotes is
@


1.162
log
@Support binary COPY through psql.  Also improve detection of write errors
during COPY OUT.  Andreas Pflug, some editorialization by moi.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.161 2006/04/02 20:08:20 neilc Exp $
d2265 1
a2265 1
testdb=&gt; <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
d2273 1
a2273 1
testdb=&gt; <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" &lt; my_file.txt` '\''</userinput>
d2277 1
a2277 1
    line, it passes <literal>sed -e "s/'/\\\'/g" &lt; my_file.txt</literal>
d2280 1
a2280 1
    <literal>-e</literal> and <literal>s/'/\\'/g</literal>. When
@


1.161
log
@Rewrite much of psql's \connect code, for the sake of code clarity and
to fix regressions introduced in the recent patch adding additional
\connect options. This is based on work by Volkan YAZICI, although
this version of the patch doesn't bear much resemblance to Volkan's
version.

\connect takes 4 optional arguments: database name, user name, host
name, and port number. If any of those parameters are omitted or
specified as "-", the value of that parameter from the previous
connection is used instead; if there is no previous connection,
the libpq default is used. Note that this behavior makes it
impossible to reuse the libpq defaults without quitting psql and
restarting it; I don't really see the use case for needing to do
that.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.160 2006/02/13 21:29:08 tgl Exp $
d747 1
d751 6
a756 4
            [ csv [ quote [ as ] '<replaceable class="parameter">character</replaceable>' ]
            [ escape [ as ] '<replaceable class="parameter">character</replaceable>' ]
            [ force quote <replaceable class="parameter">column_list</replaceable> ]
            [ force not null <replaceable class="parameter">column_list</replaceable> ] ]</literal>
@


1.160
log
@Improve documentation of --single-transaction option: fix markup, and
don't promise more than the code actually delivers.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.159 2006/02/12 04:04:32 momjian Exp $
d715 11
a725 17
        Establishes a connection to a new database and/or under a user
        name. The previous connection is closed. If <replaceable
        class="parameter">dbname</replaceable> is <literal>-</literal>
        the current database name is assumed.  Similar consideration
        applies to <replaceable class="parameter">host</replaceable> and
        <replaceable class="parameter">port</replaceable>. 
        </para>

        <para>
        If <replaceable class="parameter">username</replaceable> is
        omitted the current user name is assumed. </para>

        <para>
        As a special rule, <command>\connect</command> without any
        arguments will connect to the default database as the default
        user (as you would have gotten by starting
        <application>psql</application> without any arguments).
d730 7
a736 7
        denied, etc.), the previous connection will be kept if and only
        if <application>psql</application> is in interactive mode. When
        executing a non-interactive script, processing will immediately
        stop with an error. This distinction was chosen as a user
        convenience against typos on the one hand, and a safety
        mechanism that scripts are not accidentally acting on the wrong
        database on the other hand.
d994 10
a1003 9
        <literal>i</literal>, <literal>s</literal>, <literal>t</literal>,
        <literal>v</literal>, <literal>S</literal> stand for index,
        sequence, table, view, and system table, respectively. You can
        specify any or all of these letters, in any order, to obtain a
        listing of all the matching objects.  The letter S restricts the
        listing to system objects; without <literal>S</literal>, only
        non-system objects are shown.  If <literal>+</literal> is appended
        to the command name, each object is listed with its associated
        description, if any.
d1065 3
a1067 4
        The commands <command>GRANT</command> and
        <command>REVOKE</command> are used to set access privileges.
        See <xref linkend="sql-grant" endterm="sql-grant-title">
        for more information.
d1782 3
a1784 4
        The commands <command>GRANT</command> and
        <command>REVOKE</command> are used to set access privileges.
        See <xref linkend="sql-grant" endterm="sql-grant-title"> for
        more information.
@


1.159
log
@Add psql option:

	-1 or --single-transaction

Simon Riggs
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.158 2006/02/12 02:54:30 momjian Exp $
d471 7
a477 3
        When psql executes a script with the -f option, this additional option
        will force the script to execute as a single transaction. Either all
        SQL statements complete successfully, or no changes are applied. 
@


1.158
log
@Please find enclosed a patch that lets you use \c to connect
(optionally) to a new host and port without exiting psql.  This
eliminates, IMHO, a surprise in that you can now connect to PostgreSQL
on a differnt machine from the one where you started your session. This
should help people who use psql as an administrative tool.

David Fetter
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.157 2005/12/20 00:51:45 tgl Exp $
d466 12
@


1.157
log
@Fix broken markup.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.156 2005/12/18 02:17:16 petere Exp $
d696 1
a696 1
        <term><literal>\connect</literal> (or <literal>\c</literal>) <literal>[ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</literal></term>
d702 3
a704 1
        the current database name is assumed.
@


1.156
log
@Add new psql command \password for changing role password with client-side
password encryption.  Also alter createuser command to the same effect.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.155 2005/12/09 19:19:17 momjian Exp $
a1380 1

d1382 1
a1382 1
        <term><literal>\password [ <replaceable class=parameter>username</replaceable> ]</literal>
d1385 5
a1389 5
        Changes the password of the specified user or by default the
        current user.  This command prompts for the new password,
        encrypts it, and sends it to the server.  This makes sure that
        the new password does not appear in the command history, the
        server log, or elsewhere in cleartext.
@


1.155
log
@Remove mention that history is _now_ automatically saved on exit.  It
has been that way for a long time.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154 2005/11/04 23:14:02 petere Exp $
d1383 13
@


1.154
log
@Spellchecking run, final cleanups
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.153 2005/11/01 21:09:50 tgl Exp $
a1646 9

        <note>
        <para>
        In the current version, it is no longer necessary to save the
        command history, since that will be done automatically on
        program termination. The history is also loaded automatically
        every time <application>psql</application> starts up.
        </para>
        </note>
@


1.154.2.1
log
@Remove mention that history is _now_ automatically saved on exit.  It
has been that way for a long time.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154 2005/11/04 23:14:02 petere Exp $
d1647 9
@


1.154.2.2
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154.2.1 2005/12/09 19:19:28 momjian Exp $
a236 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.154.2.3
log
@Remove tabs from SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154.2.2 2009/08/10 02:39:16 adunstan Exp $
d237 1
a237 1
    <varlistentry>
@


1.154.2.4
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154.2.3 2009/08/15 20:22:59 momjian Exp $
d685 1
a685 1
          To print your current working directory, use <literal>\! pwd</literal>.
@


1.153
log
@Make an editorial pass over the reference pages.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.152 2005/10/30 03:01:49 momjian Exp $
d2018 1
a2018 1
        The filename that will be used to store the history list. The default
@


1.152
log
@Fix psql ref typo.

Andreas Seltenreich
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.151 2005/10/28 02:39:07 momjian Exp $
d230 3
a232 2
      Write all query output into file <replaceable
      class="parameter">filename</replaceable> in addition to the regular output source.
d605 1
a605 1
    <literal>\</literal><replaceable>digits</replaceable> (octal),
d2019 1
a2019 1
        value is <filename>~/.psql_history</filename>.  For example, using:
d2023 3
a2025 2
        in <filename>~/.psqlrc</filename> will get <application>psql</application> to
        maintain a separate history for each database.
@


1.151
log
@Remove mention that \x doesn't affect backslash commands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.150 2005/10/04 19:01:14 petere Exp $
d2110 1
a2110 1
        implicit <command>SAVEPONT</> for you, just before each command
@


1.150
log
@Clean up some messages and fix missing translation support.  Option --log
renamed to --log-file for clarity.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.149 2005/08/14 18:49:29 tgl Exp $
d1446 1
a1446 4
          the right. This option only affects how normal query results
          are displayed; the output of <application>psql</application>
          meta-commands is always presented using the regular
          format. This mode is useful if the data wouldn't fit on the
@


1.149
log
@Fix up tab completion for ROLEs and add some more completion logic for
other stuff; change \du and \dg to be role-aware (Stefan Kaltenbrunner).
Also make tab completion fetch the list of GUC variables from pg_settings
instead of having a hard-wired copy of the list (Tom Lane).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.148 2005/07/18 20:57:52 momjian Exp $
d227 1
a227 1
      <term><option>--log <replaceable class="parameter">filename</replaceable></></term>
d230 1
a230 1
      Log all query output into file <replaceable
@


1.148
log
@\pset numericsep -> numericlocale.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.147 2005/07/14 08:42:36 momjian Exp $
d966 1
a966 1
        Lists all database groups. If <replaceable
d968 2
a969 1
        those groups whose names match the pattern are listed.
d1077 1
a1077 1
        Lists all database users or only those that match <replaceable
@


1.147
log
@Change numericsep to a boolean, and make it locale-aware.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.146 2005/07/10 03:46:12 momjian Exp $
d1496 1
a1496 1
          <term><literal>numericsep</literal></term>
@


1.146
log
@Add psql \pset numericsep to allow output numbers like 100,000.0 or
100.000,0.

Eugen Nedelcu
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.145 2005/06/14 02:57:38 momjian Exp $
d1499 3
a1501 4
          Specifies the character separator between groups of three digits
          to the left of the decimal marker.  The default is <literal>''</>
          (none).  Setting this to a period also changes the decimal marker 
          to a comma.
@


1.145
log
@Add -L option to psql to log sessions.

Lorne Sunley
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.144 2005/06/13 06:36:22 neilc Exp $
d1496 12
@


1.144
log
@Per discussion on -hackers, this patch changes psql's "expanded" output
mode to only affect the presentation of normal query results, not the
output of psql slash commands. Documentation updated. I also made
some unrelated minor psql cleanup. Per suggestion from Stuart Cooper.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.143 2005/06/13 02:40:08 neilc Exp $
d226 11
@


1.143
log
@SGML cleanup: consistently use "endterm" in <xref>s that link to the
reference page for SQL commands, so that the link text is italicized.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.142 2005/06/10 16:31:48 momjian Exp $
d436 2
a437 2
      Turn on the extended table formatting mode. This is equivalent to the
      command <command>\x</command>.
d1392 1
a1392 1
	  is enough.)
d1432 7
a1438 4
          format is enabled, all output has two columns with the column
          name on the left and the data on the right. This mode is
          useful if the data wouldn't fit on the screen in the normal
          <quote>horizontal</quote> mode.
d1728 1
a1728 1
        Toggles extended table formatting mode. As such it is equivalent to
@


1.142
log
@Add space before :DBNAME for proper \set expansion.

Andreas Seltenreich
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.141 2005/06/10 16:26:59 neilc Exp $
d1039 3
a1041 3
        The commands <xref linkend="SQL-GRANT"> and
        <xref linkend="SQL-REVOKE">
        are used to set access privileges.  See <xref linkend="SQL-GRANT">
d1743 4
a1746 4
        The commands <xref linkend="SQL-GRANT"> and
        <xref linkend="SQL-REVOKE">
        are used to set access privileges.  See <xref linkend="SQL-GRANT">
        for more information.
@


1.141
log
@Minor cleanup of documentation for recently-added HISTFILE psql variable.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.140 2005/06/10 15:34:25 momjian Exp $
d1997 1
a1997 1
\set HISTFILE ~/.psql_history-:DBNAME
@


1.140
log
@the following patch makes the filename used to store the readline
history customizable through a variable named HISTFILE, analogous to
psql's already implemented HISTCONTROL and HISTSIZE variables, and
bash's HISTFILE-Variable.

The motivation was to be able to get psql to maintain separate
histories for separate databases.  This is now easily achievable
through a line like the following in ~/.psqlrc:

\set HISTFILE ~/.psql_history-:DBNAME

Andreas Seltenreich
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.139 2005/06/09 15:27:26 momjian Exp $
d1994 2
a1995 3
        This variable contains the filename used to save the history.
        Its default value is <filename>~/.psql_history</filename>.
        For example, use:
d1999 1
a1999 1
        in your <filename>~/.psqlrc</filename> will get psql to
@


1.139
log
@I've created a patch which adds support for troff "-ms" output to
psql.  i.e. "\pset format troff-ms".  The patch also corrects some
problems with the "latex" format, notably defining an extra column in
the output table, and correcting some alignment issues; it also
changes the output to match the border setting as documented in the
manual page and as shown with the "aligned" format.

The troff-ms output is mostly identical to the latex output allowing
for the differences between the two typesetters.

The output should be saved in a file and piped as follows:

  cat file | tbl | troff -T ps -ms > file.ps
or
  tbl file | troff -T ps -ms > file.ps

Because it contains tabs, you'll need to redirect psql output or use
"script", rather than pasting from a terminal window, due to the tabs
which can be replaced with spaces.

Roger Leigh
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.138 2005/06/02 01:23:48 momjian Exp $
d1991 22
@


1.138
log
@Add support for \x hex strings in psql variables.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.137 2005/05/30 15:24:23 momjian Exp $
d1389 4
a1392 3
          <literal>aligned</literal>, <literal>html</literal>, or
          <literal>latex</literal>. Unique abbreviations are allowed.
          (That would mean one letter is enough.)
@


1.137
log
@Update psql docs for recent octal-only string behavior.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.136 2005/05/29 03:32:18 momjian Exp $
d592 3
a594 2
    <literal>\n</literal> (new line), <literal>\t</literal> (tab), and
    <literal>\</literal><replaceable>digits</replaceable> (octal).
@


1.136
log
@Add reference to libpq environment variables for client applications.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.135 2005/04/28 13:09:59 momjian Exp $
d592 2
a593 5
    <literal>\n</literal> (new line), <literal>\t</literal> (tab),
    <literal>\</literal><replaceable>digits</replaceable>,
    <literal>\0</literal><replaceable>digits</replaceable>, and
    <literal>\0x</literal><replaceable>digits</replaceable> (the
    character with the given decimal, octal, or hexadecimal code).
d2367 1
a2367 6
        The character with the indicated numeric code is substituted.
        If <replaceable class="parameter">digits</replaceable> starts
        with <literal>0x</literal> the rest of the characters are
        interpreted as hexadecimal; otherwise if the first digit is
        <literal>0</literal> the digits are interpreted as octal;
        otherwise the digits are read as a decimal number.
@


1.135
log
@Add psql \set ON_ERROR_ROLLBACK to allow statements in a transaction to
error without affecting the entire transaction.  Valid values are
"on|interactive|off".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.134 2005/03/14 06:19:01 tgl Exp $
d2762 8
@


1.134
log
@Note that the -F and -R command line options only affect unaligned
output mode.  This was already stated in other places in the psql
reference page, but not here.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.133 2005/02/11 04:19:05 momjian Exp $
d2053 22
@


1.133
log
@Mention that some psql environment variables come from libpq and note
more variables can be found in the libpq manual section.

Mention .pgpass in the psql manual page section dealing with connection
parameters and point to the libpq section for more details.

Backpatch to 8.0.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.132 2005/01/22 23:22:19 momjian Exp $
d182 2
a183 2
      field separator. This is equivalent to <command>\pset
      fieldsep</command> or <command>\f</command>.
d286 2
a287 2
      record separator. This is equivalent to the <command>\pset
      recordsep</command> command.
@


1.132
log
@More < and > changes to ampersands.

8.0.X and HEAD.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.131 2005/01/22 22:31:52 momjian Exp $
d351 1
a351 1
      Makes <application>psql</application> prompt for the user name and
d409 2
a410 4
      Cause <application>psql</application> to prompt for a
      password before connecting to a database. This will remain set for
      the entire session, even if you change the database connection
      with the meta-command <command>\connect</command>.
d414 6
a419 7
      In the current version, <application>psql</application>
      automatically issues a password prompt whenever the server
      requests password authentication. Because this is currently based
      on a hack, the automatic recognition might mysteriously fail,
      hence this option to force a prompt. If no password prompt is
      issued and the server requires password authentication, the
      connection attempt will fail.
d421 7
d515 4
a518 1
    values.
d2470 1
a2470 1
      Default database to connect to
@


1.131
log
@More fixes for => and ->, use proper ampersand markups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130 2005/01/14 00:24:23 momjian Exp $
d2182 1
a2182 1
testdb=&gt; <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
d2186 1
a2186 1
    line, it passes <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal>
d2246 2
a2247 2
          <literal>[local:<replaceable>/dir/name</replaceable>]</literal
          >, if the Unix domain socket is not at the compiled in default
d2635 2
a2636 2
testdb(> <userinput> first integer not null default 0,</userinput>
testdb(> <userinput> second text)</userinput>
@


1.130
log
@Change Win32 client configuration files from *.txt to *.conf.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.129 2005/01/06 21:20:44 tgl Exp $
d539 1
a539 1
testdb=>
d884 1
a884 1
=> <userinput>\dd version</userinput>
d1110 1
a1110 1
=> <userinput>\echo `date`</userinput>
d1274 1
a1274 1
foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
d1820 1
a1820 1
testdb=> <userinput>\set foo bar</userinput>
d1827 1
a1827 1
testdb=> <userinput>\echo :foo</userinput>
d2157 2
a2158 2
testdb=> <userinput>\set foo 'my_table'</userinput>
testdb=> <userinput>SELECT * FROM :foo;</userinput>
d2174 2
a2175 2
testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
d2182 1
a2182 1
testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
d2387 1
a2387 1
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@@%/%R%[%033[0m%#%] '
d2572 1
a2572 1
testdb=> <userinput>\foo</userinput>
d2634 1
a2634 1
testdb=> <userinput>CREATE TABLE my_table (</userinput>
d2637 1
a2637 1
testdb-> <userinput>;</userinput>
d2642 1
a2642 1
testdb=> <userinput>\d my_table</userinput>
d2652 2
a2653 2
testdb=> <userinput>\set PROMPT1 '%n@@%m %~%R%# '</userinput>
peter@@localhost testdb=>
d2658 1
a2658 1
peter@@localhost testdb=> SELECT * FROM my_table;
d2671 1
a2671 1
peter@@localhost testdb=> <userinput>\pset border 2</userinput>
d2673 1
a2673 1
peter@@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
d2684 1
a2684 1
peter@@localhost testdb=> <userinput>\pset border 0</userinput>
d2686 1
a2686 1
peter@@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
d2695 1
a2695 1
peter@@localhost testdb=> <userinput>\pset border 1</userinput>
d2697 1
a2697 1
peter@@localhost testdb=> <userinput>\pset format unaligned</userinput>
d2699 1
a2699 1
peter@@localhost testdb=> <userinput>\pset fieldsep ","</userinput>
d2701 1
a2701 1
peter@@localhost testdb=> <userinput>\pset tuples_only</userinput>
d2703 1
a2703 1
peter@@localhost testdb=> <userinput>SELECT second, first FROM my_table;</userinput>
d2711 1
a2711 1
peter@@localhost testdb=> <userinput>\a \t \x</userinput>
d2715 1
a2715 1
peter@@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
@


1.130.4.1
log
@More < and > cleanups converted to ampersands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.131 2005/01/22 22:31:52 momjian Exp $
d539 1
a539 1
testdb=&gt;
d884 1
a884 1
=&gt; <userinput>\dd version</userinput>
d1110 1
a1110 1
=&gt; <userinput>\echo `date`</userinput>
d1274 1
a1274 1
foo=&gt; <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
d1820 1
a1820 1
testdb=&gt; <userinput>\set foo bar</userinput>
d1827 1
a1827 1
testdb=&gt; <userinput>\echo :foo</userinput>
d2157 2
a2158 2
testdb=&gt; <userinput>\set foo 'my_table'</userinput>
testdb=&gt; <userinput>SELECT * FROM :foo;</userinput>
d2174 2
a2175 2
testdb=&gt; <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
testdb=&gt; <userinput>INSERT INTO my_table VALUES (:content);</userinput>
d2182 1
a2182 1
testdb=&gt; <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
d2387 1
a2387 1
testdb=&gt; \set PROMPT1 '%[%033[1;33;40m%]%n@@%/%R%[%033[0m%#%] '
d2572 1
a2572 1
testdb=&gt; <userinput>\foo</userinput>
d2634 1
a2634 1
testdb=&gt; <userinput>CREATE TABLE my_table (</userinput>
d2637 1
a2637 1
testdb-&gt; <userinput>;</userinput>
d2642 1
a2642 1
testdb=&gt; <userinput>\d my_table</userinput>
d2652 2
a2653 2
testdb=&gt; <userinput>\set PROMPT1 '%n@@%m %~%R%# '</userinput>
peter@@localhost testdb=&gt;
d2658 1
a2658 1
peter@@localhost testdb=&gt; SELECT * FROM my_table;
d2671 1
a2671 1
peter@@localhost testdb=&gt; <userinput>\pset border 2</userinput>
d2673 1
a2673 1
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
d2684 1
a2684 1
peter@@localhost testdb=&gt; <userinput>\pset border 0</userinput>
d2686 1
a2686 1
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
d2695 1
a2695 1
peter@@localhost testdb=&gt; <userinput>\pset border 1</userinput>
d2697 1
a2697 1
peter@@localhost testdb=&gt; <userinput>\pset format unaligned</userinput>
d2699 1
a2699 1
peter@@localhost testdb=&gt; <userinput>\pset fieldsep ","</userinput>
d2701 1
a2701 1
peter@@localhost testdb=&gt; <userinput>\pset tuples_only</userinput>
d2703 1
a2703 1
peter@@localhost testdb=&gt; <userinput>SELECT second, first FROM my_table;</userinput>
d2711 1
a2711 1
peter@@localhost testdb=&gt; <userinput>\a \t \x</userinput>
d2715 1
a2715 1
peter@@localhost testdb=&gt; <userinput>SELECT * FROM my_table;</userinput>
@


1.130.4.2
log
@More < and > changes to ampersands.

8.0.X and HEAD.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130.4.1 2005/01/22 23:05:53 momjian Exp $
d2182 1
a2182 1
testdb=&gt; <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" &lt; my_file.txt` '\''</userinput>
d2186 1
a2186 1
    line, it passes <literal>sed -e "s/'/\\\'/g" &lt; my_file.txt</literal>
d2246 2
a2247 2
          <literal>[local:<replaceable>/dir/name</replaceable>]</literal>, 
          if the Unix domain socket is not at the compiled in default
d2635 2
a2636 2
testdb(&gt; <userinput> first integer not null default 0,</userinput>
testdb(&gt; <userinput> second text)</userinput>
@


1.130.4.3
log
@Mention that some psql environment variables come from libpq and note
more variables can be found in the libpq manual section.

Mention .pgpass in the psql manual page section dealing with connection
parameters and point to the libpq section for more details.

Backpatch to 8.0.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130.4.2 2005/01/22 23:23:53 momjian Exp $
d351 1
a351 1
      Forces <application>psql</application> to prompt for the user name and
d409 4
a412 2
      Forces <application>psql</application> to prompt for a
      password before connecting to a database.  
d416 7
a422 6
      <application>psql</application> should automatically prompt for a
      password whenever the server requests password authentication.
      However, currently password request detection is not totally
      reliable, hence this option to force a prompt. If no password
      prompt is issued and the server requires password authentication,
      the connection attempt will fail.
a423 7

      <para>
      This option will remain set for the entire session, even if you
      change the database connection with the meta-command
      <command>\connect</command>.
      </para>

d511 1
a511 4
    values. (For additional environment variables, see <xref
    linkend="libpq-envars">.) It is also convenient to have a
    <filename>~/.pgpass</> file to avoid regularly having to type in
    passwords. See <xref linkend="libpq-pgpass"> for more information.
d2463 1
a2463 1
      Default connection database
@


1.130.4.4
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130.4.3 2005/02/11 04:19:18 momjian Exp $
a224 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.130.4.5
log
@Remove tabs from SGML.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130.4.4 2009/08/10 02:39:12 adunstan Exp $
d225 1
a225 1
    <varlistentry>
@


1.130.4.6
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.130.4.5 2009/08/15 20:22:50 momjian Exp $
d675 1
a675 1
          To print your current working directory, use <literal>\! pwd</literal>.
@


1.129
log
@Spell APPDATA as %APPDATA%, per recommendation from Magnus.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.128 2005/01/06 18:29:08 tgl Exp $
d2528 1
a2528 1
     <filename>%APPDATA%\postgresql\psqlrc.txt</filename>.)
@


1.128
log
@Adjust lookup of client-side profile files (.pgpass and so on) as per
discussion on pgsql-hackers-win32 list.  Documentation still needs to
be tweaked --- I'm not sure how to refer to the APPDATA folder in
user documentation.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.127 2005/01/04 03:58:16 tgl Exp $
d2528 1
a2528 1
     <filename>APPDATA/postgresql/psqlrc.txt</filename>.)
d2551 1
a2551 1
     <filename>APPDATA/postgresql/psql_history</filename> on Windows.
@


1.127
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.126 2004/12/28 23:17:38 tgl Exp $
d443 3
a445 2
      Do not read the start-up file <filename>/psqlrc</filename> or
      <filename>~/.psqlrc</filename>.
d1113 1
a1113 1
        If the first argument is an unquoted <literal>-n</literal> the the trailing
d1905 2
a1906 2
         <filename>psqlrc</filename> or your
         <filename>.psqlrc</filename> file.
d2419 2
a2420 2
    history is stored in a file named <filename>.psql_history</filename>
    in your home directory and is reloaded when
a2444 11
    <term><envar>HOME</envar></term>

    <listitem>
     <para>
      Directory for initialization file (<filename>.psqlrc</filename>)
      and command history file (<filename>.psql_history</filename>).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
d2524 6
a2529 4
     read and execute commands from the the system-wide
     <filename>psqlrc</filename> file and the
     <filename>$HOME/.psqlrc</filename> file in the user's home
     directory.  See <filename><replaceable>PREFIX</>/share/psqlrc.sample</>
d2538 11
d2550 2
a2551 1
     <filename>$HOME/.psql_history</filename>.
@


1.126
log
@Make libpq default to localhost connections on machines without Unix-domain
sockets, rather than failing as it formerly did.  Revert the
thereby-obsoleted patch to make psql supply the localhost default.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.125 2004/12/27 20:13:48 tgl Exp $
d56 1
a56 1
      Print all the lines to the screen as they are read. This is more
d88 1
a88 1
      or it is a single backslash command. Thus you cannot mix
d122 2
a123 1
      Show all commands that are sent to the server. This is equivalent
d136 2
a137 2
      commands. You can use this if you wish to include similar
      functionality into your own programs. This is equivalent to
d218 1
a218 1
      List all available databases, then exits. Other non-connection
d330 1
a330 2
      etc. It is completely equivalent to the <command>\t</command>
      meta-command.
d399 1
a399 1
      Show the <application>psql</application> version.
d409 1
a409 1
      Requests that <application>psql</application> should prompt for a
d421 1
a421 1
      issued and the server requires password authentication the
d455 1
a455 1
      arguments.
d547 2
a548 2
    clarity. If the command was sent and without error, the results of the command
    are displayed on the screen.
d566 2
a567 2
    itself. These commands are what makes
    <application>psql</application> interesting for administration or
d640 1
a640 1
        general solution.
d834 1
d995 1
d1093 2
a1094 1
        all of them are unset, <filename>/bin/vi</filename> is run.
d1159 1
a1159 1
        optionally saves the output in <replaceable
d1161 1
a1161 1
        into a separate Unix shell to execute <replaceable
d1588 1
a1588 1
        that all output will be written to the query output channel, as
d1927 1
a1927 1
        entered or from a script are written to the standard output
d2313 1
a2313 1
        or a double quote, depending on whether
d2317 2
a2318 1
        a quote. In prompt 3 the sequence doesn't produce anything.
d2423 1
a2423 1
    can turn if off by putting this in a file named
d2632 2
a2633 2
testdb(> <userinput> second text</userinput>
testdb-> <userinput>);</userinput>
d2664 1
a2664 1
  You can make this table look differently by using the
@


1.125
log
@Move info about psql console code page issues out of install-win32.sgml,
where it doesn't belong, and put it in the psql reference page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.124 2004/12/13 18:05:10 petere Exp $
d241 1
a241 1
      Specifies the TCP port or the local Unix domain
d492 6
a497 5
    (or the user name, if the database name is also given). Not all
    these options are required, defaults do apply. If you omit the host
    name, <application>psql</> will connect via a Unix domain socket
    to a server on the local host, or via TCP/IP to <literal>localhost</> on machines
    that don't have Unix domain sockets. The default port number is compile-time determined.
d502 6
a507 2
    administrator should have informed you about your access rights. To
    save you some typing you can also set the environment variables
d509 1
a509 1
    <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
@


1.124
log
@Spell checker run
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.123 2004/10/06 18:39:15 momjian Exp $
d2580 34
@


1.123
log
@Suppress psql \s help display for platforms like Win32 that don't
typically install witn readline, and throw an error if they try to
access it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.122 2004/09/20 18:51:17 tgl Exp $
d496 1
a496 1
    that don't have unix domain sockets. The default port number is compile-time determined.
d1606 1
a1606 1
        <acronym>GNU</acronym> readline (or history) library.
d2371 1
a2371 1
         the line editing features of readline to work properly, these
@


1.122
log
@Fix some shortcomings in psql's autocommit-off mode concerning detection
of commands for which a transaction block should not be forced.  Recognize
VACUUM and other PreventTransactionChain commands; handle nested /* .. */
comments correctly; handle multibyte encodings correctly.
Michael Paesold with some kibitzing from Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.121 2004/08/24 00:06:51 neilc Exp $
d1606 1
a1606 1
        <acronym>GNU</acronym> history library.
@


1.121
log
@Various minor improvements to the SGML documentation: fix some incorrect
SGML markup, add a "deprecated features" section to the 8.0 release
notes, untabify release.sgml and runtime.sgml, and make some other
minor improvements.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.120 2004/08/14 23:49:07 tgl Exp $
d1878 2
a1879 1
        command.
@


1.120
log
@Fix typo, per Andreas Seltenreich.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.119 2004/07/15 03:56:04 momjian Exp $
d774 1
a774 1
        <application>PostgreSQL</application>.
@


1.119
log
@Add permission display to \db+.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.118 2004/07/13 16:48:15 momjian Exp $
d2554 1
a2554 1
      but were are not going to explain the details here as this use is
@


1.118
log
@Have \dn+ show permissions and description for schemas.

Dennis Bjorklund
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.117 2004/07/12 20:41:08 momjian Exp $
d835 2
@


1.117
log
@Add tablespace location display for psql \d.

Gavin Sherry
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.116 2004/06/18 06:13:05 tgl Exp $
d993 3
a995 1
        Non-local temporary schemas are suppressed.
@


1.116
log
@Tablespaces.  Alternate database locations are dead, long live tablespaces.

There are various things left to do: contrib dbsize and oid2name modules
need work, and so does the documentation.  Also someone should think about
COMMENT ON TABLESPACE and maybe RENAME TABLESPACE.  Also initlocation is
dead, it just doesn't know it yet.

Gavin Sherry and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.115 2004/04/22 17:38:14 neilc Exp $
d787 1
a787 1
        columns, their types, and any special
@


1.115
log
@Make psql's \d+ command indicate whether the table in question
contains OIDs. Also, minor documentation improvements to the
psql reference page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.114 2004/04/22 14:33:38 momjian Exp $
d74 1
a74 1
	
d211 1
a211 1
 
d290 1
a290 1
 
d346 1
a346 1
 
d373 1
a373 1
      </para> 
d494 1
a494 1
    name, <application>psql</> will connect via a Unix domain socket 
d568 1
a568 1
    The format of a <application>psql</application> command is the backslash, 
d570 1
a570 1
    are separated from the command verb and each other by any number of 
d632 4
a635 4
	If the current table output format is unaligned, it is switched to aligned.
	If it is not unaligned, it is set to unaligned. This command is
	kept for backwards compatibility. See <command>\pset</command> for a
	general solution.
d644 3
a646 3
	 Changes the current working directory to
	 <replaceable>directory</replaceable>. Without argument, changes
	 to the current user's home directory.
d649 5
a653 5
	<tip>
	 <para>
	  To print your current working directory, use <literal>\!pwd</literal>.
	 </para>
	</tip>
d676 27
a702 27
	Establishes a connection to a new database and/or under a user
	name. The previous connection is closed. If <replaceable
	class="parameter">dbname</replaceable> is <literal>-</literal>
	the current database name is assumed.
	</para>

	<para>
	If <replaceable class="parameter">username</replaceable> is
	omitted the current user name is assumed. </para>

	<para>
	As a special rule, <command>\connect</command> without any
	arguments will connect to the default database as the default
	user (as you would have gotten by starting
	<application>psql</application> without any arguments).
	</para>

	<para>
	If the connection attempt failed (wrong user name, access
	denied, etc.), the previous connection will be kept if and only
	if <application>psql</application> is in interactive mode. When
	executing a non-interactive script, processing will immediately
	stop with an error. This distinction was chosen as a user
	convenience against typos on the one hand, and a safety
	mechanism that scripts are not accidentally acting on the wrong
	database on the other hand.
	</para>
d708 1
a708 1
	[ ( <replaceable class="parameter">column_list</replaceable> ) ]
d710 3
a712 3
	{ <replaceable class="parameter">filename</replaceable> | stdin | stdout | pstdin | pstdout }
        [ with ] 
            [ oids ] 
d732 1
a732 1
	</para>
d734 22
a755 22
	<para>
	The syntax of the command is similar to that of the
	<acronym>SQL</acronym> <xref linkend="sql-copy"
	endterm="sql-copy-title"> command.  Note that, because of this,
	special parsing rules apply to the <command>\copy</command>
	command. In particular, the variable substitution rules and
	backslash escapes do not apply.
	</para>

	<para>
	<literal>\copy <replaceable
	class="parameter">table</replaceable> from <replaceable
	class="parameter">stdin | stdout</replaceable></literal>
	reads/writes based on the command input and output respectively.
	All rows are read from the same source that issued the command,
	continuing until <literal>\.</literal> is read or the stream
	reaches <acronym>EOF</>. Output is sent to the same place as
	command output. To read/write from
	<application>psql</application>'s standard input or output, use
	<literal>pstdin</> or <literal>pstdout</>. This option is useful
	for populating tables in-line within a SQL script file.
	</para>
d759 4
a762 4
	This operation is not as efficient as the <acronym>SQL</acronym>
	<command>COPY</command> command because all data must pass
	through the client/server connection. For large
	amounts of data the <acronym>SQL</acronym> command may be preferable.
d785 26
a810 26
	For each relation (table, view, index, or sequence) matching the
	<replaceable class="parameter">pattern</replaceable>, show all
	columns, their types, and any special
	attributes such as <literal>NOT NULL</literal> or defaults, if
	any. Associated indexes, constraints, rules, and triggers are
	also shown, as is the view definition if the relation is a view.
	(<quote>Matching the pattern</> is defined below.)
	</para>

	<para>
	The command form <literal>\d+</literal> is identical, except that
	more information is displayed: any comments associated with the
	columns of the table are shown, as is the presence of OIDs in the
	table.
	</para>

	<note>
	<para>
	If <command>\d</command> is used without a
	<replaceable class="parameter">pattern</replaceable> argument, it is
	equivalent to <command>\dtvs</command> which will show a list of
	all tables, views, and sequences. This is purely a convenience
	measure.
	</para>
	</note>
	</listitem>
d828 13
d845 1
a845 1
	If <replaceable class="parameter">pattern</replaceable>
d847 1
a847 1
	listed.
d869 2
a870 2
	no argument is given.  But in either case, only objects that have
	a description are listed.
d915 1
a915 1
	If the form <literal>\df+</literal> is used, additional information about
d928 2
a929 2
	functions.  This is implemented by ignoring functions that accept
	or return type <type>cstring</>.
d952 19
a970 19
	<listitem>
	<para>
	This is not the actual command name: the letters
	<literal>i</literal>, <literal>s</literal>, <literal>t</literal>,
	<literal>v</literal>, <literal>S</literal> stand for index,
	sequence, table, view, and system table, respectively. You can
	specify any or all of these letters, in any order, to obtain a
	listing of all the matching objects.  The letter S restricts the
	listing to system objects; without <literal>S</literal>, only
	non-system objects are shown.  If <literal>+</literal> is appended
	to the command name, each object is listed with its associated
	description, if any.
	</para>

	<para>
	If <replaceable class="parameter">pattern</replaceable> is
	specified, only objects whose names match the pattern are listed.
	</para>
	</listitem>
d976 6
a981 6
	<listitem>
	<para>
	This is an alias for <command>\lo_list</command>, which shows a
	list of large objects.
	</para>
	</listitem>
d1004 2
a1005 2
	If <replaceable class="parameter">pattern</replaceable> is
	specified, only operators whose names match the pattern are listed.
d1013 2
a1014 2
	<listitem>
	<para>
d1017 11
a1027 11
	If <replaceable class="parameter">pattern</replaceable> is
	specified, only tables, views and sequences whose names match the pattern are listed.
	</para>

	<para>
	The commands <xref linkend="SQL-GRANT"> and
	<xref linkend="SQL-REVOKE">
	are used to set access privileges.  See <xref linkend="SQL-GRANT">
	for more information.
	</para>
	</listitem>
d1092 1
a1092 1
	<para>
d1102 1
a1102 1
	</para>
d1104 8
a1111 8
	<tip>
	<para>
	If you use the <command>\o</command> command to redirect your
	query output you may wish to use <command>\qecho</command>
	instead of this command.
	</para>
	</tip>
	</listitem>
d1171 7
a1177 7
	<note>
	<para>
	To simplify typing, commands that consists of several words do
	not have to be quoted. Thus it is fine to type <userinput>\help
	alter table</userinput>.
	</para>
	</note>	
d1186 5
a1190 5
	Turns on <acronym>HTML</acronym> query output format. If the
	<acronym>HTML</acronym> format is already on, it is switched
	back to the default aligned text format. This command is for
	compatibility and convenience, but see <command>\pset</command>
	about setting other output options.
d1204 7
a1210 7
	<note>
	<para>
	If you want to see the lines on the screen as they are read you
	must set the variable <varname>ECHO</varname> to
	<literal>all</literal>.
	</para>
	</note>
d1231 18
a1248 18
	<listitem>
	<para>
	Reads the large object with <acronym>OID</acronym> <replaceable
	class="parameter">loid</replaceable> from the database and
	writes it to <replaceable
	class="parameter">filename</replaceable>. Note that this is
	subtly different from the server function
	<function>lo_export</function>, which acts with the permissions
	of the user that the database server runs as and on the server's
	file system.
	</para>
	<tip>
	<para>
	Use <command>\lo_list</command> to find out the large object's
	<acronym>OID</acronym>.
	</para>
	</tip>
	</listitem>
d1255 5
a1259 5
	<listitem>
	<para>
	Stores the file into a <productname>PostgreSQL</productname>
	large object. Optionally, it associates the given
	comment with the object. Example:
d1264 14
a1277 14
	The response indicates that the large object received object ID
	152801 which one ought to remember if one wants to access the
	object ever again. For that reason it is recommended to always
	associate a human-readable comment with every object. Those can
	then be seen with the <command>\lo_list</command> command.
	</para>

	<para>
	Note that this command is subtly different from the server-side
	<function>lo_import</function> because it acts as the local user
	on the local file system, rather than the server's user and file
	system.
	</para>
	</listitem>
d1282 7
a1288 7
	<listitem>
	<para>
	Shows a list of all <productname>PostgreSQL</productname>
	large objects currently stored in the database,
	along with any comments provided for them.
	</para>
	</listitem>
d1294 14
a1307 14
	<listitem>
	<para>
	Deletes the large object with <acronym>OID</acronym>
	<replaceable class="parameter">loid</replaceable> from the
	database.
	</para>

	<tip>
	<para>
	Use <command>\lo_list</command> to find out the large object's
	<acronym>OID</acronym>.
	</para>
	</tip>
	</listitem>
d1323 14
a1336 14
	<para>
	<quote>Query results</quote> includes all tables, command
	responses, and notices obtained from the database server, as
	well as output of various backslash commands that query the
	database (such as <command>\d</command>), but not error
	messages.
	</para>

	<tip>
	<para>
	To intersperse text output in between query results, use
	<command>\qecho</command>.
	</para>
	</tip>
d1354 52
a1405 37
	<listitem>
	<para>
	This command sets options affecting the output of query result
	tables. <replaceable class="parameter">parameter</replaceable>
	describes which option is to be set. The semantics of
	<replaceable class="parameter">value</replaceable> depend
	thereon.
	</para>

	<para>
	Adjustable printing options are:
	<variablelist>
	  <varlistentry>
	  <term><literal>format</literal></term>
	  <listitem>
	  <para>
	  Sets the output format to one of <literal>unaligned</literal>,
	  <literal>aligned</literal>, <literal>html</literal>, or
	  <literal>latex</literal>. Unique abbreviations are allowed.
	  (That would mean one letter is enough.)
	  </para>

	  <para>
	  <quote>Unaligned</quote> writes all columns of a row on a
	  line, separated by the currently active field separator. This
	  is intended to create output that might be intended to be read
	  in by other programs (tab-separated, comma-separated).
	  <quote>Aligned</quote> mode is the standard, human-readable,
	  nicely formatted text output that is default. The
	  <quote><acronym>HTML</acronym></quote> and
	  <quote>LaTeX</quote> modes put out tables that are intended to
	  be included in documents using the respective mark-up
	  language. They are not complete documents! (This might not be
	  so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
	  have a complete document wrapper.)
	  </para>
	  </listitem>
d1408 58
a1465 73
	  <varlistentry>
	  <term><literal>border</literal></term>
	  <listitem>
	  <para>
	  The second argument must be a number. In general, the higher
	  the number the more borders and lines the tables will have,
	  but this depends on the particular format. In
	  <acronym>HTML</acronym> mode, this will translate directly
	  into the <literal>border=...</literal> attribute, in the
	  others only values 0 (no border), 1 (internal dividing lines),
	  and 2 (table frame) make sense.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>expanded</literal> (or <literal>x</literal>)</term>
	  <listitem>
	  <para>
	  Toggles between regular and expanded format. When expanded
	  format is enabled, all output has two columns with the column
	  name on the left and the data on the right. This mode is
	  useful if the data wouldn't fit on the screen in the normal
	  <quote>horizontal</quote> mode.
	  </para>

	  <para>
	  Expanded mode is supported by all four output formats.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>null</literal></term>
	  <listitem>
	  <para>
	  The second argument is a string that should be printed
	  whenever a column is null. The default is not to print
	  anything, which can easily be mistaken for, say, an empty
	  string. Thus, one might choose to write <literal>\pset null
	  '(null)'</literal>.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>fieldsep</literal></term>
	  <listitem>
	  <para>
	  Specifies the field separator to be used in unaligned output
	  mode. That way one can create, for example, tab- or
	  comma-separated output, which other programs might prefer. To
	  set a tab as field separator, type <literal>\pset fieldsep
	  '\t'</literal>. The default field separator is
	  <literal>'|'</literal> (a vertical bar).
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>footer</literal></term>
	  <listitem>
	  <para>
	  Toggles the display of the default footer <literal>(x
	  rows)</literal>.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>recordsep</literal></term>
	  <listitem>
	  <para>
d1468 41
a1508 88
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
	  <listitem>
	  <para>
	  Toggles between tuples only and full display. Full display may
	  show extra information such as column headers, titles, and
	  various footers. In tuples only mode, only actual table data
	  is shown.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>title [ <replaceable class="parameter">text</replaceable> ]</literal></term>
	  <listitem>
	  <para>
	  Sets the table title for any subsequently printed tables. This
	  can be used to give your output descriptive tags. If no
	  argument is given, the title is unset.
	  </para>
	  </listitem>
	  </varlistentry>

	  <varlistentry>
	  <term><literal>tableattr</literal> (or <literal>T</literal>) <literal>[ <replaceable class="parameter">text</replaceable> ]</literal></term>
	  <listitem>
	  <para>
	  Allows you to specify any attributes to be placed inside the
	  <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
	  could for example be <literal>cellpadding</literal> or
	  <literal>bgcolor</literal>. Note that you probably don't want
	  to specify <literal>border</literal> here, as that is already
	  taken care of by <literal>\pset border</literal>.
	  </para>
	  </listitem>
	  </varlistentry>


	  <varlistentry>
	  <term><literal>pager</literal></term>
	  <listitem>
	  <para>
	  Controls use of a pager for query and <application>psql</>
	  help output. If the environment variable <envar>PAGER</envar>
	  is set, the output is piped to the specified program.
	  Otherwise a platform-dependent default (such as
	  <filename>more</filename>) is used.
	  </para>

	  <para>
	  When the pager is off, the pager is not used. When the pager
	  is on, the pager is used only when appropriate, i.e. the
	  output is to a terminal and will not fit on the screen.
	  (<application>psql</> does not do a perfect job of estimating
	  when to use the pager.) <literal>\pset pager</> turns the
	  pager on and off. Pager can also be set to <literal>always</>,
	  which causes the pager to be always used.
	  </para>
	  </listitem>
	  </varlistentry>
	</variablelist>
        </para>

        <para>
	Illustrations on how these different formats look can be seen in
	the <xref linkend="APP-PSQL-examples"
	endterm="APP-PSQL-examples-title"> section.
	</para>

	<tip>
	<para>
	There are various shortcut commands for <command>\pset</command>. See
	<command>\a</command>, <command>\C</command>, <command>\H</command>,
	<command>\t</command>, <command>\T</command>, and <command>\x</command>.
	</para>
	</tip>

	<note>
	<para>
	It is an error to call <command>\pset</command> without
	arguments. In the future this call might show the current status
	of all printing options.
	</para>
	</note>
d1510 48
a1557 1
	</listitem>
d1575 3
a1577 3
	This command is identical to <command>\echo</command> except
	that all output will be written to the query output channel, as
	set by <command>\o</command>.
d1605 8
a1612 8
	<note>
	<para>
	In the current version, it is no longer necessary to save the
	command history, since that will be done automatically on
	program termination. The history is also loaded automatically
	every time <application>psql</application> starts up.
	</para>
	</note>
d1620 31
a1650 31
	<listitem>
	<para>
	Sets the internal variable <replaceable
	class="parameter">name</replaceable> to <replaceable
	class="parameter">value</replaceable> or, if more than one value
	is given, to the concatenation of all of them. If no second
	argument is given, the variable is just set with no value. To
	unset a variable, use the <command>\unset</command> command.
	</para>

	<para>
	Valid variable names can contain characters, digits, and
	underscores. See the section <xref
	linkend="APP-PSQL-variables"
	endterm="APP-PSQL-variables-title"> below for details.
	Variable names are case-sensitive.
	</para>

	<para>
	Although you are welcome to set any variable to anything you
	want, <application>psql</application> treats several variables
	as special. They are documented in the section about variables.
	</para>

	<note>
	<para>
	This command is totally separate from the <acronym>SQL</acronym>
	command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
	</para>
	</note>
	</listitem>
d1707 1
a1707 1
	<literal>\pset expanded</literal>.
d1719 14
a1732 14
	If a <replaceable class="parameter">pattern</replaceable> is
	specified, only tables,views and sequences whose names match the pattern are listed.
	</para>

	<para>
	The commands <xref linkend="SQL-GRANT"> and
	<xref linkend="SQL-REVOKE">
	are used to set access privileges.  See <xref linkend="SQL-GRANT">
	for more information.
	</para>

	<para>
	This is an alias for <command>\dp</command> (<quote>display
	privileges</quote>).
d1780 1
a1780 1
   starts with <literal>foo</> and whose table name 
d1863 29
a1891 29
	<listitem>
	<para>
	When <literal>on</> (the default), each SQL command is automatically
	committed upon successful completion.  To postpone commit in this
	mode, you must enter a <command>BEGIN</> or <command>START
	TRANSACTION</> SQL command.  When <literal>off</> or unset, SQL
	commands are not committed until you explicitly issue
	<command>COMMIT</> or <command>END</>.  The autocommit-off
	mode works by issuing an implicit <command>BEGIN</> for you, just
	before any command that is not already in a transaction block and
	is not itself a <command>BEGIN</> or other transaction-control
	command.
	</para>

	<note>
	<para>
	 In autocommit-off mode, you must explicitly abandon any failed
	 transaction by entering <command>ABORT</> or <command>ROLLBACK</>.
	 Also keep in mind that if you exit the session
	 without committing, your work will be lost.
	</para>
	</note>

	<note>
	<para>
	 The autocommit-on mode is <productname>PostgreSQL</>'s traditional
	 behavior, but autocommit-off is closer to the SQL spec.  If you
	 prefer autocommit-off, you may wish to set it in the system-wide
         <filename>psqlrc</filename> or your 
d1893 3
a1895 3
	</para>
	</note>
	</listitem>
d1900 2
a1901 2
	<listitem>
	<para>
d1905 2
a1906 2
	</para>
	</listitem>
d1911 12
a1922 12
	<listitem>
	<para>
	If set to <literal>all</literal>, all lines
	entered or from a script are written to the standard output
	before they are parsed or executed. To select this behavior on program
	start-up, use the switch <option>-a</option>. If set to
	<literal>queries</literal>,
	<application>psql</application> merely prints all queries as
	they are sent to the server. The switch for this is
	<option>-e</option>.
	</para>
	</listitem>
d1927 11
a1937 11
	<listitem>
	<para>
	When this variable is set and a backslash command queries the
	database, the query is first shown. This way you can study the
	<productname>PostgreSQL</productname> internals and provide
	similar functionality in your own programs. (To select this behavior
	on program start-up, use the switch <option>-E</option>.)  If you set
	the variable to the value <literal>noexec</literal>, the queries are
	just shown but are not actually sent to the server and executed.
	</para>
	</listitem>
d1942 2
a1943 2
	<listitem>
	<para>
d1945 2
a1946 2
	</para>
	</listitem>
d1951 2
a1952 2
	<listitem>
	<para>
d1960 1
a1960 1
	</para>
d1967 1
a1967 1
	</listitem>
d1972 2
a1973 2
	<listitem>
	<para>
d1976 1
a1976 1
	</para>
d1983 1
a1983 1
	</listitem>
d1988 2
a1989 2
	<listitem>
	<para>
d1993 2
a1994 2
	</para>
	</listitem>
d1999 2
a2000 2
	<listitem>
	<para>
d2008 1
a2008 1
	</para>
d2015 1
a2015 1
	</listitem>
d2020 2
a2021 2
	<listitem>
	<para>
d2027 2
a2028 2
	</para>
	</listitem>
d2033 16
a2048 16
	<listitem>
	<para>
	By default, if non-interactive scripts encounter an error, such
	as a malformed <acronym>SQL</acronym> command or internal
	meta-command, processing continues. This has been the
	traditional behavior of <application>psql</application> but it
	is sometimes not desirable. If this variable is set, script
	processing will immediately terminate. If the script was called
	from another script it will terminate in the same fashion. If
	the outermost script was not called from an interactive
	<application>psql</application> session but rather using the
	<option>-f</option> option, <application>psql</application> will
	return error code 3, to distinguish this case from fatal error
	conditions (error code 1).
	</para>
	</listitem>
d2053 2
a2054 2
	<listitem>
	<para>
d2058 2
a2059 2
	</para>
	</listitem>
d2066 8
a2073 8
	<listitem>
	<para>
	These specify what the prompts <application>psql</application>
	issues should look like. See <xref
	linkend="APP-PSQL-prompting"
	endterm="APP-PSQL-prompting-title"> below.
	</para>
	</listitem>
d2078 7
a2084 7
	<listitem>
	<para>
	This variable is equivalent to the command line option
	<option>-q</option>. It is probably not too useful in
	interactive mode.
	</para>
	</listitem>
d2089 6
a2094 6
	<listitem>
	<para>
	This variable is equivalent to the command line option
	<option>-S</option>.
	</para>
	</listitem>
d2099 6
a2104 6
	<listitem>
	<para>
	This variable is equivalent to the command line option
	<option>-s</option>.
	</para>
	</listitem>
d2109 2
a2110 2
	<listitem>
	<para>
d2114 2
a2115 2
	</para>
	</listitem>
d2120 7
a2126 7
	<listitem>
	<para>
	This variable can be set to the values <literal>default</>,
	<literal>verbose</>, or <literal>terse</> to control the verbosity
	of error reports.
	</para>
	</listitem>
d2227 1
a2227 1
	<listitem>
d2241 1
a2241 1
	<listitem>
d2252 1
a2252 1
	<listitem><para>The port number at which the database server is listening.</para></listitem>
d2257 1
a2257 1
	<listitem>
d2269 1
a2269 1
	<listitem><para>The name of the current database.</para></listitem>
d2274 1
a2274 1
	<listitem><para>Like <literal>%/</literal>, but the output is <literal>~</literal>
d2280 1
a2280 1
	<listitem>
d2293 14
a2306 14
	<listitem>
	<para>
	In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
	in single-line mode, and <literal>!</literal> if the session is
	disconnected from the database (which can happen if
	<command>\connect</command> fails). In prompt 2 the sequence is
	replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
	or a double quote, depending on whether
	<application>psql</application> expects more input because the
	command wasn't terminated yet, because you are inside a
	<literal>/* ... */</literal> comment, or because you are inside
	a quote. In prompt 3 the sequence doesn't produce anything.
	</para>
	</listitem>
d2311 9
a2319 9
	<listitem>
	<para>
	Transaction status: an empty string when not in a transaction
	block, or <literal>*</> when in a transaction block, or
	<literal>!</> when in a failed transaction block, or <literal>?</>
	when the transaction state is indeterminate (for example, because
	there is no connection).
	</para>
	</listitem>
d2324 10
a2333 10
	<listitem>
	<para>
	The character with the indicated numeric code is substituted.
	If <replaceable class="parameter">digits</replaceable> starts
	with <literal>0x</literal> the rest of the characters are
	interpreted as hexadecimal; otherwise if the first digit is
	<literal>0</literal> the digits are interpreted as octal;
	otherwise the digits are read as a decimal number.
	</para>
	</listitem>
d2338 8
a2345 8
	<listitem>
	<para>
	The value of the <application>psql</application> variable
	<replaceable class="parameter">name</replaceable>. See the
	section <xref linkend="APP-PSQL-variables"
	endterm="APP-PSQL-variables-title"> for details.
	</para>
	</listitem>
d2350 7
a2356 7
	<listitem>
	<para>
	The output of <replaceable
	class="parameter">command</replaceable>, similar to ordinary
	<quote>back-tick</quote> substitution.
	</para>
	</listitem>
d2361 1
a2361 1
	<listitem>
d2376 2
a2377 2
	 terminals.
    	</para>
d2521 1
a2521 1
     <filename>psqlrc</filename> file and the  
d2523 2
a2524 2
     directory.  See <filename><replaceable>PREFIX</>/share/psqlrc.sample</> 
     for information on setting up the system-wide file.  It could be used 
@


1.114
log
@Fix filename mention in psqlrc.sample file.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.113 2004/04/22 01:53:17 momjian Exp $
d641 1
a641 1
       <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
d658 1
a658 1
        <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
d673 1
a673 1
        <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
d711 8
a718 8
        [ <literal>with</literal> ] 
            [ <literal>oids</literal> ] 
            [ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
            [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ]</literal>
            [ <literal>csv [ quote [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
                           [ <literal>escape [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
                           [ <literal>force quote</> <replaceable class="parameter">column_list</replaceable> ]
                           [ <literal>force not null</> <replaceable class="parameter">column_list</replaceable> ] ]
d780 2
a781 1
        <term><literal>\d</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d795 4
a798 2
	The command form <literal>\d+</literal> is identical, but any
	comments associated with the table columns are shown as well.
d814 1
a814 1
        <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d828 1
a828 1
        <term><literal>\dc</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d851 1
a851 1
        <term><literal>\dd</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d872 4
a875 3
        Descriptions for objects can be created with the
        <command>COMMENT</command> <acronym>SQL</acronym> command.
	</para>
d881 1
a881 1
        <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d894 1
d928 3
a930 2
        Lists all database groups or only those that match <replaceable
        class="parameter">pattern</replaceable>.
d941 10
a950 8
	This is not the actual command name: the letters i, s, t, v, S
	stand for index, sequence, table, view, and system table,
	respectively. You can specify any or all of these letters, in any
	order, to obtain a listing of all the matching objects.  The letter
	S restricts the listing to system objects; without S, only non-system
	objects are shown.
	If <literal>+</literal> is appended to the command name, each object is
	listed with its associated description, if any.
d973 1
a973 1
        <term><literal>\dn</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d999 1
a999 1
        <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d1020 1
d1043 1
a1043 1
        <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
d1077 1
a1077 1
        <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
d1103 1
a1103 1
        <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
d1115 1
a1115 1
        <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
d1146 1
a1146 1
        <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
d1184 1
a1184 1
        <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
d1204 1
d1208 2
a1209 2
        the server.  Append a <literal>+</literal> to the command name to
        see any descriptions for the databases as well.
d1216 1
a1216 1
        <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
d1240 1
a1240 1
        <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
d1279 1
a1279 1
        <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
d1339 1
a1339 1
        <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
d1472 1
a1472 1
	  <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
d1483 1
a1483 1
	  <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
d1559 1
a1559 1
        <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
d1581 1
a1581 1
        <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
d1605 1
a1605 1
        <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
d1654 1
a1654 1
        <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
d1701 1
a1701 1
        <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
d1726 1
a1726 1
        <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
d1845 4
@


1.113
log
@Add global psql config file, psql.rc.sample.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.112 2004/04/21 00:34:18 momjian Exp $
d443 1
a443 1
      Do not read the start-up file <filename>/psql.rc</filename> or
d1864 1
a1864 1
         <filename>psql.rc</filename> or your 
d2494 1
a2494 1
     <filename>psql.rc</filename> file and the  
d2496 1
a2496 1
     directory.  See <filename><replaceable>PREFIX</>/share/psql.rc.sample</> 
@


1.112
log
@Change COPY CSV keyword to be:

	FORCE QUOTE to force quotes
	FORCE NOT NULL to quote null input values
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.111 2004/04/19 17:22:30 momjian Exp $
d443 2
a444 1
      Do not read the start-up file <filename>~/.psqlrc</filename>.
d1863 3
a1865 2
	 prefer autocommit-off, you may wish to set it in
	 your <filename>.psqlrc</filename> file.
d2493 6
a2498 3
     read and execute commands from the file
     <filename>$HOME/.psqlrc</filename>. It could be used to set up
     the client or the server to taste (using the <command>\set
@


1.111
log
@Complete TODO item:

        o -Allow dump/load of CSV format

This adds new keywords to COPY and \copy:

        CSV - enable CSV mode (comma separated variable)
        QUOTE - specify quote character
        ESCAPE - specify escape character
        FORCE - force quoting of specified column
	LITERAL - suppress null comparison for columns

Doc changes included.  Regression updates coming from Andrew.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.110 2004/04/12 15:58:52 momjian Exp $
d716 2
a717 2
                           [ <literal>force</> <replaceable class="parameter">column_list</replaceable> ]
                           [ <literal>literal</> <replaceable class="parameter">column_list</replaceable> ] ]
@


1.110
log
@Change psql \copy stdin/stdout to read from command input/output.

Add pstdin/pstdout to read from psql's stdin/stdout.

BACKWARD INCOMPATIBLE CHANGE
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.109 2004/03/30 15:54:33 momjian Exp $
d714 4
@


1.109
log
@Add mention of how to use \df to find functions using/returning specific
data types.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.108 2004/03/24 03:27:46 momjian Exp $
d709 1
a709 1
	{ <replaceable class="parameter">filename</replaceable> | stdin | stdout | - }
d739 1
a739 1
	For <literal>\copy <replaceable
d741 9
a749 10
	class="parameter">filename</replaceable></literal> operations,
	<application>psql</application> adds the option of using a
	hyphen instead of <replaceable
	class="parameter">filename</replaceable>.  This causes
	<literal>\copy</literal> to read rows from the same source that
	issued the command, continuing until <literal>\.</literal> is
	read or the stream reaches <acronym>EOF</>.  This option is
	useful for populating tables in-line within a SQL script file.
	In contrast, <literal>\copy from stdin</> always reads from
	<application>psql</application>'s standard input.
a760 14
        <note>
        <para>
        Note the difference in interpretation of
        <literal>stdin</literal> and <literal>stdout</literal> between
	<literal>\copy</literal> and <command>COPY</command>.
	In <literal>\copy</literal> these always
        refer to <application>psql</application>'s input and output
        streams. In <command>COPY</command>, <literal>stdin</literal> comes
	from wherever the <command>COPY</command> itself came from (for
        example, a script run with the <option>-f</option> option), while
        <literal>stdout</literal> refers to the query output stream (see
        <command>\o</command> meta-command below).
        </para>
        </note>
@


1.108
log
@Document fallback to tcp/ip localhost connection from psql on ports
without unix domain sockets (win32).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.107 2004/03/22 03:38:24 momjian Exp $
d907 1
a907 2
	If the form
        <literal>\df+</literal> is used, additional information about
d912 6
@


1.107
log
@I just noticed that \dp outputs "Table" to indicate relations (tables,
sequences and views).  This patch allows it to handle views and
sequences.

Euler Taveira de Oliveira
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.106 2004/02/13 05:10:02 momjian Exp $
d493 3
a495 2
    name, <application>psql</> will connect via a Unix domain socket to a server on the
    local host. The default port number is compile-time determined.
@


1.106
log
@Mention psql variable names are case-sensitive.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.105 2004/02/12 19:58:16 momjian Exp $
d998 1
a998 1
        Produces a list of all available tables with their
d1001 1
a1001 1
	specified, only tables whose names match the pattern are listed.
d1698 1
a1698 1
        Produces a list of all available tables with their
d1701 1
a1701 1
	specified, only tables whose names match the pattern are listed.
@


1.105
log
@Improve \? wording, remove 'internal'.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.104 2004/01/20 23:48:56 tgl Exp $
d1616 1
@


1.104
log
@Implement '\copy from -' to support reading copy data from the same
source the \copy came from.  Also, fix prompting logic so that initial
and per-line prompts appear for all cases of reading from an interactive
terminal.  Patch by Mark Feit, with some kibitzing by Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.103 2004/01/20 19:49:34 tgl Exp $
d527 1
a527 1
       \? for help on internal slash commands
@


1.103
log
@This is a patch to support readline prompts which contain non-printing
characters, as for fancy colorized prompts.  This was nearly a direct
lift from bash-2.05b's lib/readline/display.c, per guidance from Chet Ramey.

Reece Hart
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.102 2003/12/23 23:13:14 momjian Exp $
d708 1
a708 1
	<replaceable class="parameter">filename</replaceable> | stdin | stdout
d723 3
a725 3
	This means that file accessibility and privileges are those
	of the local user, not the server, and no SQL superuser
	privileges are required.
d730 2
a731 2
	<acronym>SQL</acronym> <command>COPY</command> command.  (See its
	description for the details.)  Note that, because of this,
d737 15
d757 1
a757 1
	amounts of data the other technique may be preferable.
d765 2
a766 1
        client and server copies: in a client copy these always
d768 3
a770 3
        stream. On a server copy <literal>stdin</literal> comes from
        wherever the <command>COPY</command> itself came from (for
        example, a script run with the <option>-f</option> option), and
@


1.102
log
@Supress non-temp schemas from psql \dn display.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.101 2003/12/01 22:21:54 momjian Exp $
d2316 22
@


1.101
log
@attached is a patch that adds display of the groups a user belongs to to
\du and a \dg command to psql. It's against 7.4beta5.

Markus Bertheau <twanger@@bluetwanger.de>
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.100 2003/11/29 19:51:39 pgsql Exp $
d960 1
@


1.100
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.99 2003/11/01 01:56:29 petere Exp $
d903 11
@


1.99
log
@Spell checking, consistent terminology.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.98 2003/10/04 01:04:46 petere Exp $
@


1.99.2.1
log
@Re-add documentation for --no-readline option of psql, mistakenly removed a decade ago. Backpatch to release 7.4.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.99 2003/11/01 01:56:29 petere Exp $
a223 11
	<varlistentry>
      <term><option>-n</></term>
      <term><option>--no-readline</></term>
      <listitem>
      <para>
       Do not use readline for line editing and do not use the history.
       This can be useful to turn off tab expansion when cutting and pasting.
      </para>
      </listitem>
    </varlistentry>

@


1.99.2.2
log
@Add missing space in example.

Tim Landscheidt
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.99.2.1 2009/08/10 02:39:09 adunstan Exp $
d660 1
a660 1
	  To print your current working directory, use <literal>\! pwd</literal>.
@


1.98
log
@Change transaction status indicator in prompt from %T to %x.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.97 2003/09/12 02:40:09 momjian Exp $
d99 1
a99 1
       the same string is fed to psql's standard input.
@


1.97
log
@Remove WIN32_CONSOLE support, at the request of the author.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.96 2003/09/03 22:05:08 petere Exp $
d2257 1
a2257 1
        <term><literal>%T</literal></term>
@


1.96
log
@Pass session_authorization to the client and make psql update its prompt
accordingly.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.95 2003/08/31 17:32:24 petere Exp $
a2071 13
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>WIN32_CONSOLE</varname></term>
	<listitem>
	<para>
        This variable is only useful when working under the Win32 command
        console. As the Win32 command console uses a different encoding than
        the rest of the Windows system.  Eight-bit characters (e.g. German Umlauts)
        are corrupted. When this variable is set the command console encoding will
        be translated into ASCII encoding for input and output. 
@


1.95
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.94 2003/08/02 02:44:38 momjian Exp $
d2217 8
a2224 2
	<listitem><para>The user name you are connected as (not your local system
         user name).</para></listitem>
d2240 9
a2248 2
	<listitem><para>If the current user is a database superuser, then a
         <literal>#</literal>, otherwise a <literal>&gt;</literal>.</para></listitem>
@


1.94
log
@Remove docs that say psql \encoding doesn't track SET client_encoding.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.93 2003/07/28 00:14:42 tgl Exp $
d19 4
@


1.94.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/psql-ref.sgml,v 1.96 2003/09/03 22:05:08 petere Exp $
a19 4
 <indexterm zone="app-psql">
  <primary>psql</primary>
 </indexterm>

d2213 2
a2214 8
	<listitem>
         <para>
          The database session user name.  (The expansion of this
          value might change during a database session as the result
          of the command <command>SET SESSION
          AUTHORIZATION</command>.)
         </para>
        </listitem>
d2230 2
a2231 9
	<listitem>
         <para>
          If the session user is a database superuser, then a
          <literal>#</literal>, otherwise a <literal>&gt;</literal>.
          (The expansion of this value might change during a database
          session as the result of the command <command>SET SESSION
          AUTHORIZATION</command>.)
         </para>
        </listitem>
@


1.94.2.2
log
@Remove WIN32 console.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.94.2.1 2003/09/07 04:36:46 momjian Exp $
d2072 13
@


1.93
log
@Rename psql's VERBOSE variable to VERBOSITY, per suggestion from Bruce.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.92 2003/07/27 03:32:26 momjian Exp $
a1072 7
	<note>
	<para>
	This command will not notice changes made directly by <command>SET
        client_encoding</>.  If you use <command>\encoding</command>,
	be sure to use it to set as well as examine the encoding.
	</para>
	</note>	
@


1.92
log
@here are the patches for psql on Win32:

  psql4win32.patch  - changes in the psql source code
  psql-ref.patch    - changes in the documentation psql-ref.sgml
                      (for new builtin variable WIN32_CONSOLE)

To apply them use "patch -p 1" in the root directory of the
postgres source directory.

These patches fix the following problems of psql on Win32
(all changes only have effect #ifdef WIN32):

  a) Problem:  Static library libpq.a did not work
     Solution: Added WSAStartup() in fe-connect.c

  b) Problem:  Secret Password was echoed by psql
     Solution: Password echoing disabled in sprompt.c

  c) Problem:  8bit characters were displayed/interpreted wrong in psql
               This is due to the fact that the Win32 "console" uses a
               different encoding than the rest of the Windows system
     Solution: Introduced a new psql variable WIN32_CONSOLE
               When set with "\set WIN32_console", the function OemToChar()
               is applied after reading input and CharToOem() before
               displaying Output

Christoph Dalitz
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.91 2003/07/23 15:05:42 tgl Exp $
d2069 1
a2069 1
        <term><varname>VERBOSE</varname></term>
@


1.91
log
@Just a spot of copy-editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.90 2003/06/28 00:12:39 tgl Exp $
d2075 13
@


1.90
log
@Update psql for some features of new FE/BE protocol.  There is a
client-side AUTOCOMMIT mode now: '\set AUTOCOMMIT off' supports
SQL-spec commit behavior.  Get rid of LO_TRANSACTION hack --- the
LO operations just work now, using libpq's ability to track the
transaction status.  Add a VERBOSE variable to control verboseness
of error message display, and add a %T prompt-string code to show
current transaction-block status.  Superuser state display in the
prompt string correctly follows SET SESSION AUTHORIZATION commands.
Control-C works to get out of COPY IN state.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.89 2003/05/14 03:26:00 tgl Exp $
d807 1
a807 1
        is specified, only matching aggregates are shown.
d819 1
a819 1
        is specified, only conversions whose name matches the pattern are
d885 2
a886 1
        is specified, only matching functions are shown. If the form
d920 1
a920 1
	specified, only objects whose name matches the pattern are listed.
d944 1
a944 1
        is specified, only schemas whose name matches the pattern are listed.
d956 1
a956 1
	specified, only operators whose name matches the pattern are listed.
d969 1
a969 1
	specified, only tables whose name matches the pattern are listed.
d1675 1
a1675 1
	specified, only tables whose name matches the pattern are listed.
@


1.89
log
@Backend support for autocommit removed, per recent discussions.  The
only remnant of this failed experiment is that the server will take
SET AUTOCOMMIT TO ON.  Still TODO: provide some client-side autocommit
logic in libpq.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.88 2003/03/25 16:15:43 petere Exp $
a1202 7
	<note>
	<para>
	See the description of the <varname>LO_TRANSACTION</varname>
	variable for important information concerning all large object
	operations.
	</para>
	</note>
a1231 8

	<note>
	<para>
	See the description of the <varname>LO_TRANSACTION</varname>
	variable for important information concerning all large object
	operations.
	</para>
	</note>
a1261 7
	<note>
	<para>
	See the description of the <varname>LO_TRANSACTION</varname>
	variable for important information concerning all large object
	operations.
	</para>
	</note>
d1790 1
a1790 1
    variable is simply set, but has no value. To unset (or delete) a
d1797 1
a1797 1
    number of them. A number of regular variables are treated specially
d1806 2
a1807 1
    such variables. A list of all specially treated variables follows.
d1812 36
d1864 1
a1864 1
	before they are parsed or executed. To specify this on program
d1868 1
a1868 1
	they are sent to the server. The option for this is
d1881 4
a1884 4
	similar functionality in your own programs. If you set the
	variable to the value <literal>noexec</literal>, the queries are
	just shown but are not actually sent to the server and
	executed.
a1980 33
        <term><varname>LO_TRANSACTION</varname></term>
	<listitem>
	<para>
	If you use the <productname>PostgreSQL</productname> large
	object interface to specially store data that does not fit into
	one row, all the operations must be contained in a transaction
	block. (See the documentation of the large object interface for
	more information.) Since <application>psql</application> has no
	way to tell if you already have a transaction in progress when
	you call one of its internal commands
	(<command>\lo_export</command>, <command>\lo_import</command>,
	<command>\lo_unlink</command>) it must take some arbitrary
	action. This action could either be to roll back any transaction
	that might already be in progress, or to commit any such
	transaction, or to do nothing at all. In the last case you must
	provide your own <command>BEGIN</command>/<command>COMMIT</command> block or the
	results will be unpredictable (usually resulting in the desired
	action's not being performed in any case).
	</para>

	<para>
	To choose what you want to do you set this variable to one of
	<literal>rollback</literal>, <literal>commit</literal>, or
	<literal>nothing</literal>. The default is to roll back the
	transaction. If you just want to load one or a few objects this
	is fine. However, if you intend to transfer many large objects,
	it might be advisable to provide one explicit transaction block
	around all commands.
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
d2017 2
a2018 2
	These specify what the prompt <application>psql</application>
	issues is supposed to look like. See <xref
d2040 2
a2041 2
	This variable is set by the command line option
	<option>-S</option>. You can unset or reset it at run time.
d2067 11
d2119 1
a2119 1
    Observe the correct number of backslashes (6)! You can resolve it
d2137 4
a2140 3
    applies: If the variable is not set, the character sequence
    <quote>colon+name</quote> is not changed. In any case you can escape
    a colon with a backslash to protect it from interpretation. (The
d2168 1
a2168 1
    The value of the respective prompt variable is printed literally,
d2240 14
a2253 1
	a quote. In prompt 3 the sequence doesn't resolve to anything.
d2262 1
d2265 3
a2267 5
	interpreted as a hexadecimal digit and the character with the
	corresponding code is substituted. If the first digit is
	<literal>0</literal> the characters are interpreted as on octal
	number and the corresponding character is substituted. Otherwise
	a decimal number is assumed.
d2298 1
a2298 1
    <literal>%%</literal>. The default prompts are equivalent to
a2478 11
      </para>
      </listitem>

      <listitem>
      <para>
      Pressing <keycombo action="simul"><keycap>Control</><keycap>C</></>
      during a <quote>copy in</quote> (data sent to
      the server) doesn't show the most ideal of behaviors. If you get a
      message such as <errorname>COPY state must be terminated
      first</errorname>, simply reset the connection by entering <literal>\c
      - -</literal>.
@


1.88
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/psql-ref.sgml,v 1.87 2003/03/24 18:33:52 momjian Exp $
d91 5
a95 3
      If <quote>autocommit</quote> is on, multiple queries in a single
      string are processed in a single transaction.

@


1.87
log
@Prevent multiple queries in a single string into a single transaction
when autocommit is off, and document grouping when autocommit is on.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
a2490 10

  <note>
  <para>
  This section only shows a few examples specific to
  <application>psql</application>. If you want to learn
  <acronym>SQL</acronym> or get familiar with
  <productname>PostgreSQL</productname>, you might wish to read the
  &cite-tutorial;.
  </para>
  </note>
@


1.86
log
@Another big editing pass for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.85 2003/02/13 05:37:43 momjian Exp $
d89 5
@


1.85
log
@This patch fixes an error in the usage message for 'clusterdb', and
makes a few editorial changes to the documentation.


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.84 2003/01/07 20:56:06 tgl Exp $
d23 1
a23 1
   <arg><replaceable class="parameter">options</replaceable></arg>
d25 1
a25 1
   <arg><replaceable class="parameter">user</replaceable></arg></arg>
d72 2
a73 2
      <term><option>-c <replaceable class="parameter">query</replaceable></></term>
      <term><option>--command <replaceable class="parameter">query</replaceable></></term>
d77 1
a77 1
      query string, <replaceable class="parameter">query</replaceable>,
d81 2
a82 2
      <replaceable class="parameter">query</replaceable> must be either
      a query string that is completely parsable by the backend (i.e.,
d111 1
a111 1
      Show all queries that are sent to the backend. This is equivalent
d123 1
a123 1
      Echoes the actual queries generated by \d and other backslash
d138 1
a138 1
      as the source of queries instead of reading queries interactively.
d182 1
a182 1
      <application>postmaster</application> is running. If host begins
d194 1
a194 1
      Turns on <acronym>HTML</acronym> tabular output. This is
d206 1
a206 1
      Lists all available databases, then exits. Other non-connection
d230 2
a231 3
      Specifies the TCP/IP port or, by omission, the local Unix domain
      socket file extension on which the
      <application>postmaster</application> is listening for
d286 1
a286 1
      each query is sent to the backend, with the option to cancel
d297 1
a297 1
      Runs in single-line mode where a newline terminates a query, as a
d347 1
a347 1
      password because the backend requires it are really two different
d359 1
a359 1
      Connects to the database as the user <replaceable
d372 1
a372 1
      Performs a variable assignment, like the <command>\set</command>
d388 1
a388 1
      Shows the <application>psql</application> version.
d406 1
a406 1
      automatically issues a password prompt whenever the backend
d410 1
a410 1
      issued and the backend requires password authentication the
d421 1
a421 1
      Turns on extended row format mode. This is equivalent to the
d442 1
a442 1
      Shows help about <application>psql</application> command line
d457 2
a458 2
   file not found) occurs, 2 if the connection to the backend went bad
   and the session is not interactive, and 3 if an error occurred in a
d497 1
a497 1
    privileges, postmaster is not running on the server, etc.),
d503 1
a503 1
    <title>Entering Queries</title>
d525 5
a529 5
    At the prompt, the user may type in <acronym>SQL</acronym> queries.
    Ordinarily, input lines are sent to the backend when a
    query-terminating semicolon is reached. An end of line does not
    terminate a query! Thus queries can be spread over several lines for
    clarity. If the query was sent and without error, the query results
d534 1
a534 1
    Whenever a query is executed, <application>psql</application> also polls
d588 10
a597 5
    Some commands take an <acronym>SQL</acronym> identifier
    (such as a table name) as argument. These arguments follow the
    syntax rules of <acronym>SQL</acronym> regarding double quotes: an
    identifier without double quotes is coerced to lower-case, while
    whitespace within double quotes is included in the argument.
d604 1
a604 1
    arguments and continues parsing <acronym>SQL</acronym> queries, if
d619 2
a620 2
	If the current table output format is unaligned, switch to aligned.
	If it is not unaligned, set it to unaligned. This command is
d631 2
a632 2
	 Change the current working directory to
	 <replaceable>directory</replaceable>. Without argument, change
d648 1
a648 1
        Set the title of any tables being printed as the result of a
d708 1
a708 1
        endterm="SQL-COPY-title"> command, but instead of the backend's
d711 1
a711 1
        routes the data between the backend and the local file system.
d719 2
a720 2
	<acronym>SQL</acronym> <command>COPY</command> command (see its
	description for the details). Note that, because of this,
d730 1
a730 1
	through the client/server IP or socket connection. For large
d739 1
a739 1
        frontend and backend copies: in a frontend copy these always
d741 1
a741 1
        stream. On a backend copy <literal>stdin</literal> comes from
d799 1
a799 1
        class="parameter">pattern</replaceable> (a regular expression)
d852 1
a852 1
        <command>COMMENT ON</command> <acronym>SQL</acronym> command.
a853 8

        <note>
        <para>
        <productname>PostgreSQL</productname> stores the object
        descriptions in the <structname>pg_description</> system table.
        </para>
        </note>

d862 1
a862 1
        Lists all available domains (derived types). If <replaceable
d906 1
a906 1
	If <quote>+</quote> is appended to the command name, each object is
d911 1
a911 1
	If a <replaceable class="parameter">pattern</replaceable> is
d947 1
a947 1
	If a <replaceable class="parameter">pattern</replaceable> is
d959 2
a960 2
        associated access permissions.
	If a <replaceable class="parameter">pattern</replaceable> is
d967 1
a967 1
	are used to set access permissions.  See <xref linkend="SQL-GRANT">
d990 1
a990 1
        Lists all database users, or only those that match <replaceable
d1062 1
a1062 1
        Sets the client encoding.  Without an argument, this command
d1068 1
a1068 1
        CLIENT_ENCODING</>.  If you use <literal>\encoding</literal>,
d1082 1
a1082 1
        is pipe (<literal>|</literal>). See also
d1095 1
a1095 1
        Sends the current query input buffer to the backend and
d1111 1
a1111 1
        Give syntax help on the specified <acronym>SQL</acronym>
d1116 1
a1116 1
        asterisk (<quote>*</quote>), then syntax help on all
d1168 2
a1169 2
        List the names, owners, and encodings of all the databases in
        the server.  Append a <quote>+</quote> to the command name to
d1213 1
a1213 1
	<quote>large object</quote>. Optionally, it associates the given
d1219 1
a1219 1
	The response indicates that the large object received object id
d1248 1
a1248 1
	<quote>large objects</quote> currently stored in the database,
d1290 1
a1290 2
        specified, the query output will be reset to
        <filename>stdout</filename>.
d1347 1
a1347 1
	  <quote>Unaligned</quote> writes all fields of a tuple on a
d1383 1
a1383 1
	  format is enabled, all output has two columns with the field
d1390 1
a1390 1
	  Expanded mode is supported by all four output modes.
d1400 1
a1400 1
	  whenever a field is null. The default is not to print
d1417 1
a1417 1
	  <literal>'|'</literal> (a <quote>pipe</quote> symbol).
a1461 7

	  <note>
	  <para>
	  This formerly only affected <acronym>HTML</acronym> mode. You
	  can now set titles in any output format.
	  </para>
	  </note>
d1503 3
d1535 1
a1535 1
        Quit the <application>psql</application> program.
d1602 3
a1604 2
	underscores. See the section about
	<application>psql</application> variables for details.
d1639 1
a1639 1
        Allows you to specify options to be placed within the
d1675 1
a1675 1
        Toggles extended row format mode. As such it is equivalent to
d1687 1
a1687 1
        associated access permissions.
d1695 1
a1695 1
	are used to set access permissions.  See <xref linkend="SQL-GRANT">
d1701 1
a1701 1
	permissions</quote>).
d1724 1
a1724 2
        Get help information about the backslash (<quote>\</quote>)
        commands.
d1735 7
a1741 18
   object name(s) to be displayed.  Patterns are interpreted similarly
   to SQL identifiers, in that unquoted letters are forced to lowercase,
   while double quotes (<literal>"</>) protect letters from case conversion
   and allow incorporation of whitespace into the identifier.  Within
   double quotes, paired double quotes reduce to a single double quote in
   the resulting name.  For example, <literal>FOO"BAR"BAZ</> is interpreted
   as <literal>fooBARbaz</>, and <literal>"A weird"" name"</> becomes
   <literal>A weird" name</>.
  </para>

  <para>
   More interestingly, <literal>\d</> patterns allow the use of
   <literal>*</> to mean <quote>any sequence of characters</>, and
   <literal>?</> to mean <quote>any single character</>.  (This notation
   is comparable to Unix shell filename patterns.)  Advanced users can
   also use regular-expression notations such as character classes, for
   example <literal>[0-9]</> to match <quote>any digit</>.  To make any of
   these pattern-matching characters be interpreted literally, surround it
d1748 1
a1748 1
   <literal> \dt foo*.bar*</> displays all tables in schemas whose name
d1770 2
a1771 3
    features similar to common Unix command shells. This feature is new
    and not very sophisticated, yet, but there are plans to expand it in
    the future. Variables are simply name/value pairs, where the value
d1778 2
a1779 2
    sets the variable <quote>foo</quote> to the value
    <quote>bar</quote>. To retrieve the content of the variable, precede
d1822 2
d1840 1
a1840 1
	If set to <quote><literal>all</literal></quote>, all lines
d1844 1
a1844 1
	<quote><literal>queries</literal></quote>,
d1846 1
a1846 1
	they are sent to the backend. The option for this is
d1861 1
a1861 1
	just shown but are not actually sent to the backend and
d1871 1
a1871 3
        The current client multibyte encoding. If you are not set up to
        use multibyte characters, this variable will always contain
        <quote>SQL_ASCII</quote>.
d1891 1
a1891 1
        <application>bash</application>.
d1907 1
a1907 1
        <application>bash</application>.
d1939 1
a1939 1
        <application>bash</application>.
d1964 1
a1964 1
	one tuple, all the operations must be contained in a transaction
d1974 1
a1974 2
	provide your own <command>BEGIN
	TRANSACTION</command>/<command>COMMIT</command> block or the
d1981 2
a1982 2
	<quote>rollback</quote>, <quote>commit</quote>, or
	<quote>nothing</quote>. The default is to roll back the
d1996 1
a1996 1
	as a malformed <acronym>SQL</acronym> query or internal
d2029 1
a2029 1
	issues is supposed to look like. See <quote><xref
d2031 1
a2031 1
	endterm="APP-PSQL-prompting-title"></quote> below.
a2079 2
    </para>

d2106 1
a2106 1
    copy the contents of a file into a field. First load the file into a
d2114 2
a2115 2
    they don't cause a syntax error when the third line is processed. This
    could be done with the program <application>sed</application>:
d2123 1
a2123 1
    quotes and execute <filename>sed</filename> with the arguments
d2125 1
a2125 1
    <application>sed</application> parses this it will replace the two
d2136 1
a2136 1
    Since colons may legally appear in queries, the following rule
d2141 1
a2141 1
    embedded query languages, such as <application>ecpg</application>.
d2158 3
a2160 3
    <application>psql</application> requests a new query. Prompt 2 is
    issued when more input is expected during query input because the
    query was not terminated with a semicolon or a quote was not closed.
d2163 1
a2163 1
    tuples on the terminal.
d2168 1
a2168 1
    except where a percent sign (<quote>%</quote>) is encountered.
d2191 1
a2191 1
          The host name of the database server, truncated after the
d2216 1
a2216 1
	<listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
d2223 1
a2223 1
         <quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
d2230 2
a2231 2
	In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if
	in single-line mode, and <quote>!</quote> if the session is
d2234 1
a2234 1
	replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
d2237 1
a2237 1
	query wasn't terminated yet, because you are inside a
d2263 1
a2263 1
	The value of the <application>psql</application>, variable
d2265 2
a2266 2
	section <quote><xref linkend="APP-PSQL-variables"
	endterm="APP-PSQL-variables-title"></quote> for details.
d2309 1
a2309 3
    <acronym>SQL</acronym> parser. When available,
    <application>psql</application> is automatically built to use these
    features. If for some reason you do not like the tab completion, you
d2318 1
a2318 1
    <application>readline</application> feature. Read its documentation
d2448 1
a2448 1
      but I am not going to explain the details here as this use is
d2453 1
a2453 1
Field separator is "oo",
d2471 2
a2472 1
      Pressing Control-C during a <quote>copy in</quote> (data sent to
d2474 2
a2475 2
      message such as <quote>COPY state must be terminated
      first</quote>, simply reset the connection by entering <literal>\c
d2493 1
a2493 1
  Tutorial that is included in the distribution.
d2498 1
a2498 1
  The first example shows how to spread a query over several lines of
d2505 1
a2505 1
CREATE
d2517 1
a2517 2
  At this point you decide to change the prompt to something more
  interesting:
@


1.84
log
@Apply the proper version of Christopher Kings-Lynne's describe patch
(ie, the one with describe-schema support).  Minor code review.
Adjust display of casts to use standard type names.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.83 2003/01/07 18:46:52 momjian Exp $
d1066 2
a1067 2
        Sets the client encoding, if you are using multibyte encodings.
        Without an argument, this command shows the current encoding.
d1172 3
a1174 6
        List all the databases in the server as well as their owners.
        Append a <quote>+</quote> to the command name to see any
        descriptions for the databases as well. If your
        <productname>PostgreSQL</productname> installation was compiled
        with multibyte encoding support, the encoding scheme of each
        database is shown as well.
@


1.83
log
@Document that psql \encoding doesn't see SET CLIENT_ENCODING changes.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.82 2003/01/06 18:53:24 petere Exp $
d801 24
a874 23
        <term><literal>\dc</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
        <listitem>
        <para>
        Lists all available conversions (between encodings). If <replaceable
        class="parameter">pattern</replaceable>
        is specified, only matching conversions are shown.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\dC</literal></term>
        <listitem>
        <para>
        Lists all available type casts.  Casts can be explicit, explicit and assignment
	or implicit, and are used to change a variable from one type to another.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
d934 13
d1071 3
a1073 2
	This command does not see changes made by <command>SET
        CLIENT_ENCODING</>.
@


1.82
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/psql-ref.sgml,v 1.81 2002/12/12 21:02:19 momjian Exp $
d1055 6
@


1.81
log
@TODO marked as done:

	* Add schema, cast, and conversion backslash commands to psql

I had to create a new publically available function,
pg_conversion_is_visible, as it seemed to be missing from the catalogs.
This required me to do no small amount of hacking around in namespace.c

I have updated the \? help and sgml docs.

\dc - list conversions [PATTERN]
\dC - list casts
\dn list schemas

I didn't support patterns with casts as there's nothing obvious to match
against.

Catalog version incremented --- initdb required.

Christopher Kings-Lynne
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.80 2002/11/08 19:12:21 momjian Exp $
a448 4

  <para>
   Long options are not available on all platforms.
  </para>
@


1.80
log
@Here is a patch that does just that, while maintaining the
"traditional" behavior, so the change should be transparent. Use the
command "\pset pager always" to turn it on. Anything else does the
normal toggle between "on" and "off"

Greg Sabino Mullane
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.79 2002/10/19 00:22:14 tgl Exp $
d849 23
@


1.79
log
@Fix psql's \copy to accept table names containing schemas, as well as
a column list.  Bring its parsing of quoted names and quoted strings
somewhat up to speed --- I believe it now handles all non-error cases
the same way the backend would, but weird boundary conditions are not
necessarily done the same way.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.78 2002/10/11 23:03:48 petere Exp $
d1459 4
a1462 3
	  Toggles the use of a pager for query and <application>psql</> help output. If the
	  environment variable <envar>PAGER</envar> is set, the output
	  is piped to the specified program. Otherwise a platform-dependent default (such as
d1467 7
a1473 8
	  In any case, <application>psql</application> only uses the
	  pager if it seems appropriate. That means among other things
	  that the output is to a terminal and that the table would
	  normally not fit on the screen. Because of the modular nature
	  of the printing routines it is not always possible to predict
	  the number of lines that will actually be printed. For that
	  reason <application>psql</application> might not appear very
	  discriminating about when to use the pager.
@


1.78
log
@Assorted reference page updates
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.77 2002/09/22 20:44:22 tgl Exp $
d695 1
d709 1
a709 3
        reading or writing the specified file, and consequently
        requiring backend access and special user privilege, as well as
        being bound to the file system accessible by the backend,
d712 3
@


1.77
log
@Make \dS work more like it used to, viz, show only system objects.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.76 2002/09/21 18:32:54 petere Exp $
a45 6
  <para>
   If so configured, <application>psql</application> understands both
   standard Unix short options, and <acronym>GNU</acronym>-style long
   options. The latter are not available on all systems.
  </para>

d449 4
@


1.76
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.75 2002/09/18 20:09:32 petere Exp $
d887 3
a889 1
	order, to obtain a listing of all the matching objects.
@


1.75
log
@Update installation instructions and put mostly everything in one place.
Also, some editing in PL/Perl and PL/Python chapters.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.74 2002/08/27 20:16:48 petere Exp $
d54 2
a55 1
      <term>-a, --echo-all</term>
d60 1
a60 1
      equivalent to setting the variable <envar>ECHO</envar> to
d67 2
a68 1
      <term>-A, --no-align</term>
d78 2
a79 1
      <term>-c, --command <replaceable class="parameter">query</replaceable></term>
d88 1
a88 1
      a query string that is completely parseable by the backend (i.e.,
d100 2
a101 1
      <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
d113 2
a114 1
      <term>-e, --echo-queries</term>
d118 1
a118 1
      to setting the variable <envar>ECHO</envar> to
d125 2
a126 1
      <term>-E, --echo-hidden</term>
d132 1
a132 1
      setting the variable <envar>ECHO_HIDDEN</envar> from within
d139 2
a140 1
      <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
d171 2
a172 1
      <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
d183 2
a184 1
      <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
d189 1
a189 1
      with a slash, it is used as the directory for the unix domain
d196 2
a197 1
      <term>-H, --html</term>
d208 2
a209 1
      <term>-l, --list</term>
d220 2
a221 1
      <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
d232 2
a233 1
      <term>-p, --port <replaceable class="parameter">port</replaceable></term>
d247 2
a248 1
      <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
d261 2
a262 1
      <term>-q</term>
d270 1
a270 1
      <envar>QUIET</envar> variable to achieve the same effect.
d276 2
a277 1
      <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
d288 2
a289 1
      <term>-s, --single-step</term>
d300 2
a301 1
      <term>-S, --single-line</term>
d320 2
a321 1
      <term>-t, --tuples-only</term>
d332 2
a333 1
      <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
d344 1
a344 1
      <term>-u</term>
d362 2
a363 1
      <term>-U, --username <replaceable class="parameter">username</replaceable></term>
d374 3
a376 1
      <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
d391 2
a392 1
      <term>-V, --version</term>
d401 2
a402 1
      <term>-W, --password</term>
d424 2
a425 1
      <term>-x, --expanded</term>
d435 2
a436 1
      <term>-X, --no-psqlrc</term>
d445 2
a446 1
      <term>-?, --help</term>
d466 1
a466 1
   script and the variable <envar>ON_ERROR_STOP</envar> was set.
d489 1
a489 1
    name psql will connect via a Unix domain socket to a server on the
d587 5
a591 5
    Arguments that are quoted in <quote>backticks</quote>
    (<literal>`</literal>) are taken as a command line that is passed to
    the shell. The output of the command (with any trailing newline
    removed) is taken as the argument value. The above escape sequences
    also apply in backticks.
d696 1
a696 1
        <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
d702 1
a702 1
            [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ]
d869 1
a869 1
        To reduce clutter, <literal>\df</> does not show datatype I/O
d1118 1
a1118 1
	must set the variable <envar>ECHO</envar> to
d1163 1
a1163 1
	See the description of the <envar>LO_TRANSACTION</envar>
d1200 1
a1200 1
	See the description of the <envar>LO_TRANSACTION</envar>
d1237 1
a1237 1
	See the description of the <envar>LO_TRANSACTION</envar>
d1457 1
a1457 1
	  Toggles the use of a pager for query and psql help output. If the
d1806 1
a1806 1
        <term><envar>DBNAME</envar></term>
d1817 1
a1817 1
        <term><envar>ECHO</envar></term>
d1833 1
a1833 1
        <term><envar>ECHO_HIDDEN</envar></term>
d1840 1
a1840 1
	variable to the value <quote>noexec</quote>, the queries are
d1848 1
a1848 1
        <term><envar>ENCODING</envar></term>
d1859 1
a1859 1
        <term><envar>HISTCONTROL</envar></term>
d1880 1
a1880 1
        <term><envar>HISTSIZE</envar></term>
d1896 1
a1896 1
        <term><envar>HOST</envar></term>
d1907 1
a1907 1
        <term><envar>IGNOREEOF</envar></term>
d1910 7
a1916 6
         If unset, sending an EOF character (usually Control-D) to an
         interactive session of <application>psql</application> will
         terminate the application. If set to a numeric value, that many
         EOF characters are ignored before the application terminates.
         If the variable is set but has no numeric value, the default is
         10.
d1928 1
a1928 1
        <term><envar>LASTOID</envar></term>
d1931 1
a1931 1
        The value of the last affected oid, as returned from an
d1941 1
a1941 1
        <term><envar>LO_TRANSACTION</envar></term>
d1975 1
a1975 1
        <term><envar>ON_ERROR_STOP</envar></term>
d1995 1
a1995 1
        <term><envar>PORT</envar></term>
d2006 3
a2008 1
        <term><envar>PROMPT1</envar>, <envar>PROMPT2</envar>, <envar>PROMPT3</envar></term>
d2020 1
a2020 1
        <term><envar>QUIET</envar></term>
d2031 1
a2031 1
        <term><envar>SINGLELINE</envar></term>
d2041 1
a2041 1
        <term><envar>SINGLESTEP</envar></term>
d2051 1
a2051 1
        <term><envar>USER</envar></term>
d2139 2
a2140 2
    to your preference. The three variables <envar>PROMPT1</envar>,
    <envar>PROMPT2</envar>, and <envar>PROMPT3</envar> contain strings
d2285 1
a2285 1
    <title>Readline</title>
d2288 2
a2289 2
    <application>psql</application> supports the readline and history
    libraries for convenient line editing and retrieval. The command
@


1.74
log
@Enable locale, so case conversion (identifier processing) and number
formatting (\timing) works correctly.  Change "Total time" to "Time"
since there is nothing that "total" refers to.  Remove non-multibyte
code.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.73 2002/08/23 01:27:44 tgl Exp $
a2275 27
    </para>

    <para>
    If you have the readline library installed but
    <application>psql</application> does not seem to use it, you must
    make sure that <productname>PostgreSQL</productname>'s top-level
    <filename>configure</filename> script finds it.
    <filename>configure</filename> needs to find both the library
    <filename>libreadline.a</filename> (or a shared library equivalent)
    <emphasis>and</emphasis> the header files
    <filename>readline.h</filename> and <filename>history.h</filename>
    (or <filename>readline/readline.h</filename> and
    <filename>readline/history.h</filename>) in appropriate directories.
    If you have the library and header files installed in an obscure
    place you must tell <filename>configure</filename> about them, for
    example:
<programlisting>
$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
</programlisting>
    Then you have to recompile <application>psql</application> (not
    necessarily the entire code tree).
    </para>

    <para>
    The <acronym>GNU</acronym> readline library can be obtained from the
    <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at
    <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
@


1.73
log
@Add note that explains that \df omits functions it thinks are I/O functions.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.72 2002/08/16 20:34:06 momjian Exp $
d1594 1
a1594 1
         Toggles a display of how long each query takes, in milliseconds.
@


1.72
log
@Move pg_controldata from /contrib to src/bin.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.71 2002/08/10 19:35:00 tgl Exp $
d838 9
@


1.71
log
@psql prints its version number in its startup message, per recent
discussion.  Also, cause the \timing command to display time in a
format consistent with the backend's EXPLAIN ANALYZE output.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.70 2002/08/10 03:56:23 tgl Exp $
d25 1
a25 1
     <arg><replaceable class="parameter">user</replaceable></arg></arg>
@


1.70
log
@psql backslash commands are schema-aware.  Pattern matching behavior
follows recent pghackers discussion.  This commit includes all the
relevant fixes from Greg Mullane's patch of 24-June.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/psql-ref.sgml,v 1.69 2002/07/28 15:22:21 petere Exp $
d491 1
a491 1
Welcome to psql, the PostgreSQL interactive terminal.
d1585 1
a1585 1
         Toggles a display of how long each query takes in seconds.
@


1.69
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/psql-ref.sgml,v 1.68 2002/07/15 01:56:25 momjian Exp $
d541 1
a541 1
    To include whitespace into an argument you must quote it with a
d554 2
a555 2
    it is taken as a variable and the value of the variable is taken as
    the argument instead.
d561 1
a561 1
    the shell. The output of the command (with a trailing newline
d567 1
a567 1
    Some commands take the name of an <acronym>SQL</acronym> identifier
d570 2
a571 3
    identifier without double quotes is coerced to lower-case. For all
    other commands double quotes are not special and will become part of
    the argument.
d734 1
a734 1
        <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
d738 3
a740 3
	Shows all columns of <replaceable
	class="parameter">relation</replaceable> (which could be a
	table, view, index, or sequence), their types, and any special
d742 3
a744 4
	any. If the relation is, in fact, a table, any defined indices,
	primary keys, unique constraints and check constraints are also
	listed. If the relation is a view, the view definition is also
	shown.
d754 2
a755 1
	If <command>\d</command> is called without any arguments, it is
d778 1
a778 1
        <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
d781 4
a784 3
        Shows the descriptions of <replaceable
        class="parameter">object</replaceable> (which can be a regular
        expression), or of all objects if no argument is given.
d790 4
a793 4
              Object descriptions
  Name   |   What   |        Description
---------+----------+---------------------------
 version | function | PostgreSQL version string
d799 1
a799 1
        Descriptions for objects can be generated with the
d806 1
a806 1
        descriptions in the pg_description system table.
d819 1
a819 1
        class="parameter">pattern</replaceable> (a regular expression)
d833 1
a833 1
        class="parameter">pattern</replaceable> (a regular expression)
d847 1
a847 1
	This is not the actual command name: The letters i, s, t, v, S
d849 4
a852 2
	respectively. You can specify any or all of them in any order to
	obtain a listing of them, together with who the owner is.
d856 2
a857 5
	If <replaceable class="parameter">pattern</replaceable> is
	specified, it is a regular expression that restricts the listing
	to those objects whose name matches. If one appends a
	<quote>+</quote> to the command name, each object is listed with
	its associated description, if any.
d875 1
a875 1
        <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
d879 2
a880 2
        If <replaceable class="parameter">name</replaceable> is
        specified, only operators with that name will be shown.
d890 11
a900 3
	This is an alias for <command>\z</command> which was included
	for its greater mnemonic value (<quote>display
	permissions</quote>).
d922 1
a922 1
        Lists all configured users or only those that match <replaceable
d1618 4
a1621 43
        Produces a list of all tables in the database with their
        appropriate access permissions listed. If an argument is given
        it is taken as a regular expression which limits the listing to
        those tables which match it.
        </para>

	<para>
<programlisting>
test=&gt; <userinput>\z</userinput>
Access permissions for database "test"
 Relation |           Access permissions
----------+-------------------------------------
 my_table | {"=r","joe=arwR", "group staff=ar"}
(1 row )
</programlisting>
        Read this as follows:

	<itemizedlist>
          <listitem>
          <para>
          <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
          (<command>SELECT</command>) permission on the table.
	  </para>
	  </listitem>

	  <listitem>
	  <para>
	  <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
	  read, write (<command>UPDATE</command>,
	  <command>DELETE</command>), <quote>append</quote>
	  (<command>INSERT</command>) permissions, and permission to
	  create rules on the table.
	  </para>
	  </listitem>

	  <listitem>
	  <para>
	  <literal>"group staff=ar"</literal>: Group
	  <literal>staff</literal> has <command>SELECT</command> and
	  <command>INSERT</command> permission.
	  </para>
	  </listitem>
	</itemizedlist>
d1627 2
a1628 1
	are used to set access permissions.
d1631 4
d1664 40
d2418 4
a2421 3
      In some earlier life <application>psql</application> allowed the
      first argument to start directly after the (single-letter)
      command. For compatibility this is still supported to some extent
d2423 1
a2423 1
      discouraged. But if you get strange messages, keep this in mind.
d2438 2
a2439 1
      up.
@


1.68
log
@Fix \? and \pset pager handling.  \? wasn't honoring pager before.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.67 2002/06/20 16:00:43 momjian Exp $
a6 4
 <docinfo>
  <date>2000-12-25</date>
 </docinfo>

d20 8
a27 11
  <refsynopsisdiv>
    <refsynopsisdivinfo>
      <date>1999-10-26</date>
    </refsynopsisdivinfo>

    <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis>

  <refsect2 id="R2-APP-PSQL-1">
    <refsect2info>
      <date>1998-09-26</date>
    </refsect2info>
d29 2
a30 1
    <title>Summary</title>
d41 1
d43 2
a44 1
  </refsect2>
d46 5
a50 1
</refsynopsisdiv>
d52 12
a63 4
<refsect1 id="R1-APP-PSQL-1">
  <refsect1info>
    <date>1998-10-26</date>
  </refsect1info>
d65 30
a94 1
  <title>Description</title>
d96 11
a106 6
  <refsect2 id="R2-APP-PSQL-connecting">
    <refsect2info>
      <date>2000-01-14</date>
    </refsect2info>
   
    <title>Connecting To A Database</title>
d108 10
a117 24
    <para>
    <application>psql</application> is a regular
    <productname>PostgreSQL</productname> client application. In order
    to connect to a database you need to know the name of your target
    database, the host name and port number of the server and what user
    name you want to connect as. <application>psql</application> can be
    told about those parameters via command line options, namely
    <option>-d</option>, <option>-h</option>, <option>-p</option>, and
    <option>-U</option> respectively. If an argument is found that does
    not belong to any option it will be interpreted as the database name
    (or the user name, if the database name is also given). Not all
    these options are required, defaults do apply. If you omit the host
    name psql will connect via a Unix domain socket to a server on the
    local host. The default port number is compile-time determined.
    Since the database server uses the same default, you will not have
    to specify the port in most cases. The default user name is your
    Unix user name, as is the default database name. Note that you can't
    just connect to any database under any user name. Your database
    administrator should have informed you about your access rights. To
    save you some typing you can also set the environment variables
    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
    <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
    values.
    </para>
d119 12
a130 6
    <para>
    If the connection could not be made for any reason (e.g., insufficient
    privileges, postmaster is not running on the server, etc.),
    <application>psql</application> will return an error and terminate.
    </para>
  </refsect2>
d132 10
a141 4
  <refsect2 id="R2-APP-PSQL-4">
    <refsect2info>
      <date>1998-09-26</date>
    </refsect2info>
d143 4
a146 1
    <title>Entering Queries</title>
d148 14
a161 8
    <para>
    In normal operation, <application>psql</application> provides a
    prompt with the name of the database to which
    <application>psql</application> is currently connected, followed by
    the string <literal>=&gt;</literal>. For example,
<programlisting>
$ <userinput>psql testdb</userinput>
Welcome to psql, the PostgreSQL interactive terminal.
d163 10
a172 5
Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit
d174 11
a184 3
testdb=>
</programlisting>
    </para>
d186 21
a206 8
    <para>
    At the prompt, the user may type in <acronym>SQL</acronym> queries.
    Ordinarily, input lines are sent to the backend when a
    query-terminating semicolon is reached. An end of line does not
    terminate a query! Thus queries can be spread over several lines for
    clarity. If the query was sent and without error, the query results
    are displayed on the screen.
    </para>
d208 10
a217 8
    <para>
    Whenever a query is executed, <application>psql</application> also polls
    for asynchronous notification events generated by
    <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
    <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
    </para>
  </refsect2>
</refsect1>
d219 13
a231 4
<refsect1 id="R1-APP-PSQL-2">
    <refsect1info>
      <date>1998-09-26</date>
    </refsect1info>
d233 289
a521 1
    <title><application>psql</application> Meta-Commands</title>
d1406 2
a1407 229
	  </varlistentry>


	  <varlistentry>
	  <term><literal>pager</literal></term>
	  <listitem>
	  <para>
	  Toggles the use of a pager for query and psql help output. If the
	  environment variable <envar>PAGER</envar> is set, the output
	  is piped to the specified program. Otherwise
	  <filename>more</filename> is used.
	  </para>

	  <para>
	  In any case, <application>psql</application> only uses the
	  pager if it seems appropriate. That means among other things
	  that the output is to a terminal and that the table would
	  normally not fit on the screen. Because of the modular nature
	  of the printing routines it is not always possible to predict
	  the number of lines that will actually be printed. For that
	  reason <application>psql</application> might not appear very
	  discriminating about when to use the pager.
	  </para>
	  </listitem>
	  </varlistentry>
	</variablelist>
	Illustrations on how these different formats look can be seen in
	the <xref linkend="APP-PSQL-examples"
	endterm="APP-PSQL-examples-title"> section.
	</para>

	<tip>
	<para>
	There are various shortcut commands for <command>\pset</command>. See
	<command>\a</command>, <command>\C</command>, <command>\H</command>,
	<command>\t</command>, <command>\T</command>, and <command>\x</command>.
	</para>
	</tip>

	<note>
	<para>
	It is an error to call <command>\pset</command> without
	arguments. In the future this call might show the current status
	of all printing options.
	</para>
	</note>

	</listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\q</literal></term>
        <listitem>
        <para>
        Quit the <application>psql</application> program.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
        <listitem>
        <para>
	This command is identical to <command>\echo</command> except
	that all output will be written to the query output channel, as
	set by <command>\o</command>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\r</literal></term>
        <listitem>
        <para>
        Resets (clears) the query buffer.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
        <listitem>
        <para>
        Print or save the command line history to <replaceable
        class="parameter">filename</replaceable>. If <replaceable
        class="parameter">filename</replaceable> is omitted, the history
        is written to the standard output. This option is only available
        if <application>psql</application> is configured to use the
        <acronym>GNU</acronym> history library.
        </para>

	<note>
	<para>
	In the current version, it is no longer necessary to save the
	command history, since that will be done automatically on
	program termination. The history is also loaded automatically
	every time <application>psql</application> starts up.
	</para>
	</note>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>

	<listitem>
	<para>
	Sets the internal variable <replaceable
	class="parameter">name</replaceable> to <replaceable
	class="parameter">value</replaceable> or, if more than one value
	is given, to the concatenation of all of them. If no second
	argument is given, the variable is just set with no value. To
	unset a variable, use the <command>\unset</command> command.
	</para>

	<para>
	Valid variable names can contain characters, digits, and
	underscores. See the section about
	<application>psql</application> variables for details.
	</para>

	<para>
	Although you are welcome to set any variable to anything you
	want, <application>psql</application> treats several variables
	as special. They are documented in the section about variables.
	</para>

	<note>
	<para>
	This command is totally separate from the <acronym>SQL</acronym>
	command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
	</para>
	</note>
	</listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\t</literal></term>
        <listitem>
        <para>
        Toggles the display of output column name headings and row count
        footer. This command is equivalent to <literal>\pset
        tuples_only</literal> and is provided for convenience.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
        <listitem>
        <para>
        Allows you to specify options to be placed within the
        <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
        output mode. This command is equivalent to <literal>\pset
        tableattr <replaceable
        class="parameter">table_options</replaceable></literal>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
       <term><literal>\timing</literal></term>
        <listitem>
        <para>
         Toggles a display of how long each query takes in seconds.
        </para>
       </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
        <listitem>
        <para>
        Outputs the current query buffer to the file <replaceable
        class="parameter">filename</replaceable> or pipes it to the Unix
        command <replaceable class="parameter">command</replaceable>.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\x</literal></term>
        <listitem>
        <para>
        Toggles extended row format mode. As such it is equivalent to
	<literal>\pset expanded</literal>.
       </para>
       </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
        <listitem>
        <para>
        Produces a list of all tables in the database with their
        appropriate access permissions listed. If an argument is given
        it is taken as a regular expression which limits the listing to
        those tables which match it.
        </para>

	<para>
<programlisting>
test=&gt; <userinput>\z</userinput>
Access permissions for database "test"
 Relation |           Access permissions
----------+-------------------------------------
 my_table | {"=r","joe=arwR", "group staff=ar"}
(1 row )
</programlisting>
        Read this as follows:

	<itemizedlist>
          <listitem>
          <para>
          <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
          (<command>SELECT</command>) permission on the table.
	  </para>
	  </listitem>
d1409 2
d1413 4
a1416 5
	  <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
	  read, write (<command>UPDATE</command>,
	  <command>DELETE</command>), <quote>append</quote>
	  (<command>INSERT</command>) permissions, and permission to
	  create rules on the table.
a1417 1
	  </listitem>
a1418 1
	  <listitem>
d1420 8
a1427 3
	  <literal>"group staff=ar"</literal>: Group
	  <literal>staff</literal> has <command>SELECT</command> and
	  <command>INSERT</command> permission.
d1430 5
a1434 1
	</itemizedlist>
d1437 1
d1439 3
a1441 3
	The commands <xref linkend="SQL-GRANT"> and
	<xref linkend="SQL-REVOKE">
	are used to set access permissions.
d1443 1
d1445 7
a1451 2
        </listitem>
      </varlistentry>
d1453 1
a1453 22

      <varlistentry>
        <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
        <listitem>
        <para>
        Escapes to a separate Unix shell or executes the Unix command
        <replaceable class="parameter">command</replaceable>. The
        arguments are not further interpreted, the shell will see them
        as is.
        </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>\?</literal></term>
        <listitem>
        <para>
        Get help information about the backslash (<quote>\</quote>)
        commands.
        </para>
        </listitem>
a1455 197
    </variablelist>
  </para>
</refsect1>



<refsect1 id="R1-APP-PSQL-3">
  <refsect1info>
    <date>1998-09-26</date>
  </refsect1info>

  <title>Command-line Options</title>

  <para>
  If so configured, <application>psql</application> understands both
  standard Unix short options, and <acronym>GNU</acronym>-style long
  options. The latter are not available on all systems.
  </para>

  <para>
  <variablelist>
    <varlistentry>
      <term>-a, --echo-all</term>
      <listitem>
      <para>
      Print all the lines to the screen as they are read. This is more
      useful for script processing rather than interactive mode. This is
      equivalent to setting the variable <envar>ECHO</envar> to
      <literal>all</literal>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-A, --no-align</term>
      <listitem>
      <para>
      Switches to unaligned output mode. (The default output mode is
      otherwise aligned.)
      </para>
      </listitem>
    </varlistentry>

	
    <varlistentry>
      <term>-c, --command <replaceable class="parameter">query</replaceable></term>
      <listitem>
      <para>
      Specifies that <application>psql</application> is to execute one
      query string, <replaceable class="parameter">query</replaceable>,
      and then exit. This is useful in shell scripts.
      </para>
      <para>
      <replaceable class="parameter">query</replaceable> must be either
      a query string that is completely parseable by the backend (i.e.,
      it contains no <application>psql</application> specific features),
      or it is a single backslash command. Thus you cannot mix
      <acronym>SQL</acronym> and <application>psql</application>
      meta-commands. To achieve that, you could pipe the string into
      <application>psql</application>, like this: <literal>echo "\x \\
      select * from foo;" | psql</literal>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
      <listitem>
      <para>
      Specifies the name of the database to connect to. This is
      equivalent to specifying <replaceable
      class="parameter">dbname</replaceable> as the first non-option
      argument on the command line.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-e, --echo-queries</term>
      <listitem>
      <para>
      Show all queries that are sent to the backend. This is equivalent
      to setting the variable <envar>ECHO</envar> to
      <literal>queries</literal>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-E, --echo-hidden</term>
      <listitem>
      <para>
      Echoes the actual queries generated by \d and other backslash
      commands. You can use this if you wish to include similar
      functionality into your own programs. This is equivalent to
      setting the variable <envar>ECHO_HIDDEN</envar> from within
      <application>psql</application>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
      <listitem>
      <para>
      Use the file <replaceable class="parameter">filename</replaceable>
      as the source of queries instead of reading queries interactively.
      After the file is processed, <application>psql</application>
      terminates. This is in many ways equivalent to the internal
      command <command>\i</command>.
      </para>

      <para>
       If <replaceable>filename</replaceable> is <literal>-</literal>
       (hyphen), then standard input is read.
      </para>

      <para>
      Using this option is subtly different from writing <literal>psql
      &lt; <replaceable
      class="parameter">filename</replaceable></literal>. In general,
      both will do what you expect, but using <literal>-f</literal>
      enables some nice features such as error messages with line
      numbers. There is also a slight chance that using this option will
      reduce the start-up overhead. On the other hand, the variant using
      the shell's input redirection is (in theory) guaranteed to yield
      exactly the same output that you would have gotten had you entered
      everything by hand.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      field separator. This is equivalent to <command>\pset
      fieldsep</command> or <command>\f</command>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
      <listitem>
      <para>
      Specifies the host name of the machine on which the
      <application>postmaster</application> is running. If host begins
      with a slash, it is used as the directory for the unix domain
      socket.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-H, --html</term>
      <listitem>
      <para>
      Turns on <acronym>HTML</acronym> tabular output. This is
      equivalent to <literal>\pset format html</literal> or the
      <command>\H</command> command.
      </para>
      </listitem>
    </varlistentry>

 
    <varlistentry>
      <term>-l, --list</term>
      <listitem>
      <para>
      Lists all available databases, then exits. Other non-connection
      options are ignored. This is similar to the internal command
      <command>\list</command>.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
      <listitem>
      <para>
      Put all query output into file <replaceable
      class="parameter">filename</replaceable>. This is equivalent to
      the command <command>\o</command>.
      </para>
      </listitem>
    </varlistentry>
d1457 8
a1465 13
    <varlistentry>
      <term>-p, --port <replaceable class="parameter">port</replaceable></term>
      <listitem>
      <para>
      Specifies the TCP/IP port or, by omission, the local Unix domain
      socket file extension on which the
      <application>postmaster</application> is listening for
      connections. Defaults to the value of the <envar>PGPORT</envar>
      environment variable or, if not set, to the port specified at
      compile time, usually 5432.
      </para>
      </listitem>
    </varlistentry>
d1467 10
a1477 12
    <varlistentry>
      <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
      <listitem>
      <para>
      Allows you to specify printing options in the style of
      <command>\pset</command> on the command line. Note that here you
      have to separate name and value with an equal sign instead of a
      space. Thus to set the output format to LaTeX, you could write
      <literal>-P format=latex</literal>.
      </para>
      </listitem>
    </varlistentry>
d1479 8
a1487 13
    <varlistentry>
      <term>-q</term>
      <listitem>
      <para>
      Specifies that <application>psql</application> should do its work
      quietly. By default, it prints welcome messages and various
      informational output. If this option is used, none of this
      happens. This is useful with the <option>-c</option> option.
      Within <application>psql</application> you can also set the
      <envar>QUIET</envar> variable to achieve the same effect.
      </para>
      </listitem>
    </varlistentry>
d1489 11
d1501 10
a1510 10
    <varlistentry>
      <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      record separator. This is equivalent to the <command>\pset
      recordsep</command> command.
      </para>
      </listitem>
    </varlistentry>
a1511 11
 
    <varlistentry>
      <term>-s, --single-step</term>
      <listitem>
      <para>
      Run in single-step mode. That means the user is prompted before
      each query is sent to the backend, with the option to cancel
      execution as well. Use this to debug scripts.
      </para>
      </listitem>
    </varlistentry>
d1513 2
d1516 9
a1524 7
    <varlistentry>
      <term>-S, --single-line</term>
      <listitem>
      <para>
      Runs in single-line mode where a newline terminates a query, as a
      semicolon does.
      </para>
d1526 5
a1530 10
      <note>
      <para>
      This mode is provided for those who insist on it, but you are not
      necessarily encouraged to use it. In particular, if you mix
      <acronym>SQL</acronym> and meta-commands on a line the order of
      execution might not always be clear to the inexperienced user.
      </para>
      </note>
      </listitem>
    </varlistentry>
d1532 5
d1538 8
a1545 10
    <varlistentry>
      <term>-t, --tuples-only</term>
      <listitem>
      <para>
      Turn off printing of column names and result row count footers,
      etc. It is completely equivalent to the <command>\t</command>
      meta-command.
      </para>
      </listitem>
    </varlistentry>
d1548 10
a1557 10
    <varlistentry>
      <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
      <listitem>
      <para>
      Allows you to specify options to be placed within the
      <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
      <command>\pset</command> for details.
      </para>
      </listitem>
    </varlistentry>
a1558 8
 
    <varlistentry>
      <term>-u</term>
      <listitem>
      <para>
      Makes <application>psql</application> prompt for the user name and
      password before connecting to the database.
      </para>
d1560 12
a1571 9
      <para>
      This option is deprecated, as it is conceptually flawed.
      (Prompting for a non-default user name and prompting for a
      password because the backend requires it are really two different
      things.) You are encouraged to look at the <option>-U</option> and
      <option>-W</option> options instead.
      </para>
      </listitem>
    </varlistentry>
d1574 8
a1581 10
    <varlistentry>
      <term>-U, --username <replaceable class="parameter">username</replaceable></term>
      <listitem>
      <para>
      Connects to the database as the user <replaceable
      class="parameter">username</replaceable> instead of the default.
      (You must have permission to do so, of course.)
      </para> 
      </listitem>
    </varlistentry>
d1584 10
a1593 14
    <varlistentry>
      <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
      <listitem>
      <para>
      Performs a variable assignment, like the <command>\set</command>
      internal command. Note that you must separate name and value, if
      any, by an equal sign on the command line. To unset a variable,
      leave off the equal sign. To just set a variable without a value,
      use the equal sign but leave off the value. These assignments are
      done during a very early stage of start-up, so variables reserved
      for internal purposes might get overwritten later.
      </para>
      </listitem>
    </varlistentry>
d1596 9
a1604 8
    <varlistentry>
      <term>-V, --version</term>
      <listitem>
      <para>
      Shows the <application>psql</application> version.
      </para>
      </listitem>
    </varlistentry>
d1607 9
a1615 9
    <varlistentry>
      <term>-W, --password</term>
      <listitem>
      <para>
      Requests that <application>psql</application> should prompt for a
      password before connecting to a database. This will remain set for
      the entire session, even if you change the database connection
      with the meta-command <command>\connect</command>.
      </para>
d1617 10
a1626 11
      <para>
      In the current version, <application>psql</application>
      automatically issues a password prompt whenever the backend
      requests password authentication. Because this is currently based
      on a hack, the automatic recognition might mysteriously fail,
      hence this option to force a prompt. If no password prompt is
      issued and the backend requires password authentication the
      connection attempt will fail.
      </para>
      </listitem>
    </varlistentry>
d1628 7
d1636 9
a1644 9
    <varlistentry>
      <term>-x, --expanded</term>
      <listitem>
      <para>
      Turns on extended row format mode. This is equivalent to the
      command <command>\x</command>.
      </para>
      </listitem>
    </varlistentry>
d1646 9
d1656 5
a1660 8
    <varlistentry>
      <term>-X, --no-psqlrc</term>
      <listitem>
      <para>
      Do not read the start-up file <filename>~/.psqlrc</filename>.
      </para>
      </listitem>
    </varlistentry>
d1662 2
a1664 9
    <varlistentry>
      <term>-?, --help</term>
      <listitem>
      <para>
      Shows help about <application>psql</application> command line
      arguments.
      </para>
      </listitem>
    </varlistentry>
d1666 11
a1676 2
  </variablelist>
  </para>
a1677 1
</refsect1>
d1679 9
d1689 3
a1691 4
<refsect1 id="R1-APP-PSQL-4">
    <refsect1info>
      <date>1998-09-27</date>
    </refsect1info>
d1693 2
a1694 1
    <title>Advanced features</title>
d1696 1
a1696 1
  <refsect2 id="APP-PSQL-variables">
d2012 1
a2012 2
  </refsect2>

d2014 2
a2015 2
  <refsect2 id="APP-PSQL-sql-interpol">
    <title id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title>
d2079 1
a2079 2
  </refsect2>

d2081 1
a2081 1
  <refsect2 id="APP-PSQL-prompting">
d2229 1
a2229 22
   </refsect2>

  <refsect2 id="APP-PSQL-MISC">
    <title id="APP-PSQL-MISC-title">Miscellaneous</title>

    <para>
    <application>psql</application> returns 0 to the shell if it
    finished normally, 1 if a fatal error of its own (out of memory,
    file not found) occurs, 2 if the connection to the backend went bad
    and the session is not interactive, and 3 if an error occurred in a
    script and the variable <envar>ON_ERROR_STOP</envar> was set.
    </para>

    <para>
    Before starting up, <application>psql</application> attempts to read
    and execute commands from the file
    <filename>$HOME/.psqlrc</filename>. It could be used to set up the
    client or the server to taste (using the <command>\set </command>
    and <command>SET</command> commands).
    </para>

  </refsect2>
d2231 2
a2232 2
  <refsect2>
    <title><acronym>GNU</acronym> readline</title>
d2282 1
d2284 134
d2419 8
d2428 9
d2438 2
a2439 1
</refsect1>
d2442 1
a2442 1
<refsect1 id="APP-PSQL-examples">
d2557 1
a2557 54
</refsect1>


<refsect1>
  <refsect1info>
    <date>1999-10-27</date>
  </refsect1info>

  <title>Appendix</title>

  <refsect2>
    <title>Bugs and Issues</title>

    <itemizedlist>
      <listitem>
      <para>
      In some earlier life <application>psql</application> allowed the
      first argument to start directly after the (single-letter)
      command. For compatibility this is still supported to some extent
      but I am not going to explain the details here as this use is
      discouraged. But if you get strange messages, keep this in mind.
      For example
<programlisting>
testdb=> <userinput>\foo</userinput>
Field separator is "oo",
</programlisting>
      which is perhaps not what one would expect.
      </para>
      </listitem>

      <listitem>
      <para>
      <application>psql</application> only works smoothly with servers
      of the same version. That does not mean other combinations will
      fail outright, but subtle and not-so-subtle problems might come
      up.
      </para>
      </listitem>

      <listitem>
      <para>
      Pressing Control-C during a <quote>copy in</quote> (data sent to
      the server) doesn't show the most ideal of behaviors. If you get a
      message such as <quote>COPY state must be terminated
      first</quote>, simply reset the connection by entering <literal>\c
      - -</literal>.
      </para>
      </listitem>

    </itemizedlist>

  </refsect2>

</refsect1>
@


1.67
log
@Improve COPY syntax to use WITH clause, keep backward compatibility.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.66 2002/03/22 19:20:44 petere Exp $
d1039 1
a1039 1
	  Toggles the list of a pager to do table output. If the
d1053 1
a1053 1
	  discriminating about when to use the pager and when not to.
@


1.66
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.65 2002/03/20 19:43:30 tgl Exp $
d39 7
a45 7
     <application>psql</application> is a terminal-based front-end to 
     <productname>PostgreSQL</productname>. It enables you to type in queries
     interactively, issue them to <productname>PostgreSQL</productname>, and see
     the query results. Alternatively, input can be from a file.
     In addition, it provides a number of meta-commands and
     various shell-like features to facilitate writing scripts and automating a wide
     variety of tasks.
d67 22
a88 20
    <application>psql</application> is a regular <productname>PostgreSQL</productname>
    client application. In order to connect to a database you need to know the
    name of your target database, the host name and port number of the server
    and what user name you want to connect as. <application>psql</application> can be
    told about those parameters via command line options, namely <option>-d</option>,
    <option>-h</option>, <option>-p</option>, and <option>-U</option> respectively.
    If an argument is found that does not belong to any option it will be interpreted
    as the database name (or the user name, if the database name is also
	 given). Not all these options are required, defaults do apply.
    If you omit the host name psql will connect via a Unix domain socket
    to a server on the
    local host. The default port number is compile-time determined. Since the database
    server uses the same default, you will not have to specify the port in most
    cases. The default user name is your Unix user name, as is the default
    database name.
    Note that you can't just connect to any database under any user name. Your database
    administrator should have informed you about your access rights. To save you some typing
    you can also set the environment variables <envar>PGDATABASE</envar>,
    <envar>PGHOST</envar>, <envar>PGPORT</envar> and <envar>PGUSER</envar>
    to appropriate values.
d106 4
a109 3
    In normal operation, <application>psql</application> provides a prompt with
    the name of the database to which <application>psql</application> is currently
    connected, followed by the string <literal>=&gt;</literal>. For example,
d125 6
a130 5
    At the prompt, the user may type in <acronym>SQL</acronym> queries.  
    Ordinarily, input lines are sent to the backend when a query-terminating
    semicolon is reached. An end of line does not terminate a query! Thus queries
    can be spread over several lines for clarity. If the query was sent and without
    error, the query results are displayed on the screen.
d150 7
a156 6
    Anything you enter in <application>psql</application> that begins with an
    unquoted backslash is a <application>psql</application> meta-command that is
    processed by <application>psql</application> itself.
    These commands are what makes
    <application>psql</application> interesting for administration or scripting.
    Meta-commands are more commonly called slash or backslash commands.
d167 6
a172 5
    To include whitespace into an argument you must quote it with a single
    quote. To include a single quote into such an argument, precede it by
    a backslash. Anything contained in single quotes is furthermore subject to
    C-like substitutions for <literal>\n</literal> (new line), <literal>\t</literal>
     (tab), <literal>\</literal><replaceable>digits</replaceable>,
d174 2
a175 2
    <literal>\0x</literal><replaceable>digits</replaceable>
    (the character with the given decimal, octal, or hexadecimal code).
d180 2
a181 2
    it is taken as a variable and the value of the variable is taken as the
    argument instead.
d185 5
a189 4
    Arguments that are quoted in <quote>backticks</quote> (<literal>`</literal>)
    are taken as a command line that is passed to the shell. The output of the
    command (with a trailing newline removed) is taken as the argument value.
    The above escape sequences also apply in backticks.
d193 6
a198 5
    Some commands take the name of an <acronym>SQL</acronym> identifier (such as
    a table name) as argument. These arguments follow the syntax rules of
    <acronym>SQL</acronym> regarding double quotes: an identifier without
    double quotes is coerced to lower-case. For all other commands
    double quotes are not special and will become part of the argument.
d202 8
a209 8
    Parsing for arguments stops when another unquoted backslash occurs. This
    is taken as the beginning of a new meta-command. The special sequence
    <literal>\\</literal>
    (two backslashes) marks the end of arguments and continues parsing
    <acronym>SQL</acronym> queries, if any. That way <acronym>SQL</acronym> and
    <application>psql</application> commands can be freely mixed on a line.
    But in any case, the arguments of a meta-command cannot continue beyond the end
    of the line. 
d233 2
a234 2
	 <replaceable>directory</replaceable>.  Without argument,
	 change to the current user's home directory.
d249 7
a255 6
        Set the title of any tables being printed as the result of a query or
        unset any such title. This command is equivalent to
        <literal>\pset title <replaceable class="parameter">title</replaceable></literal>.
        (The name of this
        command derives from <quote>caption</quote>, as it was previously only
	used to set the caption in an <acronym>HTML</acronym> table.)
d264 3
a266 3
	Establishes a connection to a new database and/or under a user name. The
	previous connection is closed.
	If <replaceable class="parameter">dbname</replaceable> is <literal>-</literal>
d271 2
a272 3
	If <replaceable class="parameter">username</replaceable> is omitted
        the current user name is assumed.
	</para>
d275 4
a278 3
	As a special rule, <command>\connect</command> without any arguments will connect
	to the default database as the default user (as you would have gotten
	by starting <application>psql</application> without any arguments).
d282 8
a289 6
	If the connection attempt failed (wrong user name, access denied, etc.), the
	previous connection will be kept if and only if <application>psql</application> is
	in interactive mode. When executing a non-interactive script, processing
	will immediately stop with an error. This distinction was chosen as a user
	convenience against typos on the one hand, and a safety mechanism that
	scripts are not accidentally acting on the wrong database on the other hand.
d296 1
a296 1
        [ <literal>with oids</literal> ] { <literal>from</literal> | <literal>to</literal> }
d298 4
a301 2
        [ <literal>using delimiters</literal> '<replaceable class="parameter">characters</replaceable>' ]
        [ <literal>with null as</literal> '<replaceable class="parameter">string</replaceable>' ]
d306 8
a313 7
        Performs a frontend (client) copy. This is an operation that runs an
	<acronym>SQL</acronym> <xref linkend="SQL-COPY" endterm="SQL-COPY-title"> command,
        but instead of the backend's reading or writing the specified file, and 
        consequently requiring backend access and special user privilege, 
	as well as being bound to the file system accessible by the backend,
        <application>psql</application> reads or writes the 
        file and routes the data between the backend and the local file system.
d317 6
a322 5
	The syntax of the command is similar to that of the <acronym>SQL</acronym>
	<command>COPY</command> command (see its description for the details).
	Note that, because of this, special parsing rules apply to the
	<command>\copy</command> command. In particular, the variable
	substitution rules and backslash escapes do not apply.
d327 4
a330 4
	This operation is not as efficient as the <acronym>SQL</acronym> 
	<command>COPY</command> command because all data must pass through the
	client/server IP or socket connection. For large amounts of data the other
	technique may be preferable.
d336 8
a343 6
        Note the difference in interpretation of <literal>stdin</literal> and <literal>stdout</literal>
        between frontend and backend copies: in a frontend copy these always refer
        to <application>psql</application>'s input and output stream. On a backend
        copy <literal>stdin</literal> comes from wherever the <command>COPY</command>
        itself came from (for example, a script run with the <option>-f</option> option),
        and <literal>stdout</literal> refers to the query output stream (see
d354 2
a355 1
        Shows the copyright and distribution terms of <application>PostgreSQL</application>.
d365 8
a372 7
	Shows all columns of <replaceable class="parameter">relation</replaceable>
	(which could be a table, view, index, or sequence),
	their types, and any special attributes such as <literal>NOT NULL</literal>
	or defaults, if any.
	If the relation is, in fact, a table, any defined indices, primary keys, unique 
	constraints and check constraints are also listed.
	If the relation is a view, the view definition is also shown.
d376 2
a377 2
	The command form <literal>\d+</literal> is identical, but any comments
        associated with the table columns are shown as well.
d383 2
a384 2
	equivalent to <command>\dtvs</command> which will show a list
	of all tables, views, and sequences. This is purely a convenience
d396 4
a399 3
        Lists all available aggregate functions, together with the data type they operate on.
	If <replaceable class="parameter">pattern</replaceable>
	(a regular expression) is specified, only matching aggregates are shown.
d408 6
a413 4
        Shows the descriptions of <replaceable class="parameter">object</replaceable>
        (which can be a regular expression), or of all objects if no argument is given.
        (<quote>Object</quote> covers aggregates, functions, operators, types, relations
        (tables, views, indexes, sequences, large objects), rules, and triggers.) For example:
d425 2
a426 2
        Descriptions for objects can be generated with the <command>COMMENT ON</command>
        <acronym>SQL</acronym> command.
d431 2
a432 2
        <productname>PostgreSQL</productname> stores the object descriptions in the
        pg_description system table.
d444 3
a446 3
        Lists all available domains (derived types).
	If <replaceable class="parameter">pattern</replaceable>
	(a regular expression) is specified, only matching domains are shown.
d457 5
a461 4
        Lists available functions, together with their argument and return types.
        If <replaceable class="parameter">pattern</replaceable>
        (a regular expression) is specified, only matching functions are shown.
        If the form <literal>\df+</literal> is used, additional information about
d473 4
a476 4
	This is not the actual command name: The letters i, s, t, v, S stand for
	index, sequence, table, view, and system table, respectively. You can specify
	any or all of them in any order to obtain a listing of them, together with
	who the owner is.
d480 5
a484 4
	If <replaceable class="parameter">pattern</replaceable> is specified,
	it is a regular expression that restricts the listing to those objects
	whose name matches. If one appends a <quote>+</quote> to the command name,
	each object is listed with its associated description, if any.
d494 2
a495 1
	This is an alias for <command>\lo_list</command>, which shows a list of large objects.
d506 2
a507 2
        If <replaceable class="parameter">name</replaceable>
        is specified, only operators with that name will be shown.
d517 3
a519 2
	This is an alias for <command>\z</command> which was included for its
	greater mnemonic value (<quote>display permissions</quote>).
d529 3
a531 2
        Lists all data types or only those that match <replaceable class="parameter">pattern</replaceable>.
        The command form <literal>\dT+</literal> shows extra information.
d541 2
a542 1
        Lists all configured users or only those that match <replaceable class="parameter">pattern</replaceable>.
d553 5
a557 5
        If <replaceable class="parameter">filename</replaceable> is specified,
        the file is edited; after the editor exits, its content is copied
        back to the query buffer. If no argument is given, the current query
        buffer is copied to a temporary file which is then edited in the same
        fashion.
d561 7
a567 6
        The new query buffer is then re-parsed according to the normal rules of
        <application>psql</application>, where the whole buffer is treated as
        a single line. (Thus you cannot make scripts this way.
        Use <command>\i</command> for that.) This means also that
        if the query ends with (or rather contains) a semicolon, it is immediately
        executed. In other cases it will merely wait in the query buffer.
d572 4
a575 4
        <application>psql</application> searches the environment variables
        <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and <envar>VISUAL</envar>
        (in that order) for an editor to use. If all of them are unset,
        <filename>/bin/vi</filename> is run.
d586 2
a587 2
        Prints the arguments to the standard output, separated by one space and
        followed by a newline. This can be useful to
d599 3
a601 2
	If you use the <command>\o</command> command to redirect your query output
	you may wish to use <command>\qecho</command> instead of this command.
d625 4
a628 3
        Sets the field separator for unaligned query output. The default is
pipe (<literal>|</literal>). See also <command>\pset</command> for a generic way
	of setting output options.
d639 8
a646 6
        Sends the current query input buffer to the backend and optionally
        saves the output in <replaceable class="parameter">filename</replaceable>
        or pipes the output into a separate Unix shell to execute
        <replaceable class="parameter">command</replaceable>. A bare <literal>\g</literal>
	is virtually equivalent to a semicolon. A <literal>\g</literal> with argument
	is a <quote>one-shot</quote> alternative to the <command>\o</command> command.
d655 7
a661 7
        Give syntax help on the specified <acronym>SQL</acronym> command.  
        If <replaceable class="parameter">command</replaceable> is not specified,
        then <application>psql</application> will 
        list all the commands for which syntax help is
        available.  If <replaceable class="parameter">command</replaceable>
        is an asterisk (<quote>*</quote>), then
        syntax help on all <acronym>SQL</acronym> commands is shown.
d666 3
a668 2
	To simplify typing, commands that consists of several words do not have to be quoted.
	Thus it is fine to type <userinput>\help alter table</userinput>.
d679 5
a683 4
	Turns on <acronym>HTML</acronym> query output format. If the <acronym>HTML</acronym>
	format is already on, it is switched back to the default aligned text format. This
	command is for compatibility and convenience, but see <command>\pset</command> about
	setting other output options.
d693 3
a695 2
        Reads input from the file <replaceable class="parameter">filename</replaceable>
	and executes it as though it had been typed on the keyboard.
d699 3
a701 2
	If you want to see the lines on the screen as they are read you must set
	the variable <envar>ECHO</envar> to <literal>all</literal>.
d712 6
a717 6
        List all the databases in the server as well as their owners. Append a
        <quote>+</quote> to the command name to see any descriptions
        for the databases as well. If your <productname>PostgreSQL</productname>
	installation was
	compiled with multibyte encoding support, the encoding scheme of each
	database is shown as well.
d728 8
a735 5
	Reads the large object with <acronym>OID</acronym> <replaceable class="parameter">loid</replaceable>
	from the database and writes it to <replaceable class="parameter">filename</replaceable>.
	Note that this is subtly different from the server function <function>lo_export</function>,
	which acts with the permissions of the user that the database server runs as and
	on the server's file system.
d739 2
a740 1
	Use <command>\lo_list</command> to find out the large object's <acronym>OID</acronym>.
d745 3
a747 2
	See the description of the <envar>LO_TRANSACTION</envar> variable for
	important information concerning all large object operations.
d759 3
a761 2
	Stores the file into a <productname>PostgreSQL</productname> <quote>large object</quote>.
	Optionally, it associates the given comment with the object. Example:
d766 5
a770 5
	The response indicates that the large object received object id 152801
	which one ought to remember if one wants to access the object ever again.
	For that reason it is recommended to always associate a human-readable
	comment with every object. Those can then be seen with the
	<command>\lo_list</command> command.
d774 4
a777 3
	Note that this command is subtly different from the server-side <function>lo_import</function>
	because it acts as the local user on the local file system, rather than the server's
	user and file system.
d782 3
a784 2
	See the description of the <envar>LO_TRANSACTION</envar> variable for
	important information concerning all large object operations.
d794 3
a796 3
	Shows a list of all <productname>PostgreSQL</productname> <quote>large
	objects</quote> currently stored in the database, along with any
	comments provided for them.
d806 3
a808 2
	Deletes the large object with <acronym>OID</acronym> <replaceable class="parameter">loid</replaceable>
	from the database.
d813 2
a814 1
	Use <command>\lo_list</command> to find out the large object's <acronym>OID</acronym>.
d819 3
a821 2
	See the description of the <envar>LO_TRANSACTION</envar> variable for
	important information concerning all large object operations.
d833 5
a837 5
        Saves future query results to the file
	<replaceable class="parameter">filename</replaceable> or pipes future
        results into a separate Unix shell to execute
	<replaceable class="parameter">command</replaceable>.
        If no arguments are specified, the query output will be reset to
d842 5
a846 5
	<quote>Query results</quote> includes all tables, command responses,
        and notices obtained
	from the database server, as well as output of various backslash
	commands that query the database (such as <command>\d</command>),
        but not error messages.
d851 2
a852 1
	To intersperse text output in between query results, use <command>\qecho</command>.
d874 5
a878 4
	This command sets options affecting the output of query result tables.
	<replaceable class="parameter">parameter</replaceable> describes which option
	is to be set. The semantics of <replaceable class="parameter">value</replaceable>
	depend thereon.
d889 3
a891 2
	  <literal>aligned</literal>, <literal>html</literal>, or <literal>latex</literal>.
	  Unique abbreviations are allowed. (That would mean one letter is enough.)
d895 11
a905 10
	  <quote>Unaligned</quote> writes all fields of a tuple on a line, separated
	  by the currently active field separator. This is intended to create output
	  that might be intended to be read in by other programs (tab-separated,
	  comma-separated).
	  <quote>Aligned</quote> mode is the
	  standard, human-readable, nicely formatted text output that is default.
	  The <quote><acronym>HTML</acronym></quote> and <quote>LaTeX</quote> modes
	  put out tables that are intended to be included in documents using the
	  respective mark-up language. They are not complete documents! (This might
	  not be so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
d915 7
a921 6
	  The second argument must be a number. In general, the higher the number
	  the more borders and lines the tables will have, but this depends on
	  the particular format. In <acronym>HTML</acronym> mode, this will
	  translate directly into the <literal>border=...</literal> attribute, in
	  the others only values 0 (no border), 1 (internal dividing lines), and 2
	  (table frame) make sense.
d930 5
a934 4
	  Toggles between regular and expanded format. When expanded format is
	  enabled, all output has two columns with the field name on the left
	  and the data on the right. This mode is useful if the data wouldn't
	  fit on the screen in the normal <quote>horizontal</quote> mode.
d947 5
a951 4
	  The second argument is a string that should be printed whenever a field
	  is null. The default is not to print anything, which can easily be mistaken
	  for, say, an empty string. Thus, one might choose to write
	  <literal>\pset null '(null)'</literal>.
d960 5
a964 4
	  Specifies the field separator to be used in unaligned output mode. That way
	  one can create, for example, tab- or comma-separated output, which other
	  programs might prefer. To set a tab as field separator, type
	  <literal>\pset fieldsep '\t'</literal>. The default field separator is
d974 2
a975 1
	  Toggles the display of the default footer <literal>(x rows)</literal>.
d984 2
a985 2
          Specifies the record (line) separator to use in unaligned output mode. The default
          is a newline character.
d994 4
a997 3
	  Toggles between tuples only and full display. Full display may show
	  extra information such as column headers, titles, and various footers.
	  In tuples only mode, only actual table data is shown.
d1006 3
a1008 3
	  Sets the table title for any subsequently printed tables. This can be
	  used to give your output descriptive tags. If no argument is given,
	  the title is unset.
d1013 2
a1014 2
	  This formerly only affected <acronym>HTML</acronym> mode. You can now
	  set titles in any output format.
d1024 6
a1029 5
	  Allows you to specify any attributes to be placed inside the <acronym>HTML</acronym>
	  <sgmltag>table</sgmltag> tag. This could for example be
	  <literal>cellpadding</literal> or <literal>bgcolor</literal>. Note that you
	  probably don't want to specify <literal>border</literal> here, as
	  that is already taken care of by <literal>\pset border</literal>.
d1039 4
a1042 3
	  Toggles the list of a pager to do table output. If the environment variable
	  <envar>PAGER</envar> is set, the output is piped to the specified program.
	  Otherwise <filename>more</filename> is used.
d1046 7
a1052 6
	  In any case, <application>psql</application> only uses the pager if it
	  seems appropriate. That means among other things that the output is to
	  a terminal and that the table would normally not fit on the screen.
	  Because of the modular nature of the printing routines it is not always
	  possible to predict the number of lines that will actually be printed.
	  For that reason <application>psql</application> might not appear very
d1059 2
a1060 1
	the <xref linkend="APP-PSQL-examples" endterm="APP-PSQL-examples-title"> section.
d1073 3
a1075 2
	It is an error to call <command>\pset</command> without arguments. In the future
	this call might show the current status of all printing options.
d1097 3
a1099 3
	This command is identical to <command>\echo</command> except that
	all output will be written to the query output channel, as set by
	<command>\o</command>.
d1119 6
a1124 6
        Print or save the command line history to 
        <replaceable class="parameter">filename</replaceable>.
        If <replaceable class="parameter">filename</replaceable> is omitted,
	the history is written to the standard output.
        This option is only available if <application>psql</application> is
        configured to use the <acronym>GNU</acronym> history library.
d1129 4
a1132 5
	In the current version, it is no longer
	necessary to save the command history, since that will be done
	automatically on program termination. The history is
	also loaded automatically every time <application>psql</application>
	starts up.
d1144 6
a1149 5
	Sets the internal variable <replaceable class="parameter">name</replaceable>
	to <replaceable class="parameter">value</replaceable> or, if more than one
        value is given, to the concatenation of all of them. If no second argument
	is given, the variable is just set with no value. To unset a variable, use
        the <command>\unset</command> command.
d1153 3
a1155 2
	Valid variable names can contain characters, digits, and underscores.
        See the section about <application>psql</application> variables for details.
d1159 3
a1161 3
	Although you are welcome to set any variable to anything you want,
	<application>psql</application> treats several variables as special.
	They are documented in the section about variables.
d1166 2
a1167 2
	This command is totally separate from the <acronym>SQL</acronym> command
	<xref linkend="SQL-SET" endterm="SQL-SET-title">.
d1178 3
a1180 3
        Toggles the display of output column name headings and row count footer.
	This command is equivalent to <literal>\pset tuples_only</literal> and
	is provided for convenience.	
d1190 5
a1194 3
        Allows you to specify options to be placed within the <sgmltag>table</sgmltag>
	tag in <acronym>HTML</acronym> tabular output mode. This command is
	equivalent to <literal>\pset tableattr <replaceable class="parameter">table_options</replaceable></literal>.
d1214 3
a1216 2
        Outputs the current query buffer to the file <replaceable class="parameter">filename</replaceable>
	or pipes it to the Unix command <replaceable class="parameter">command</replaceable>.
d1237 4
a1240 3
        Produces a list of all tables in the database with their appropriate
	access permissions listed. If an argument is given it is taken as a regular
	expression which limits the listing to those tables which match it.
d1258 1
a1258 1
	  (<command>SELECT</command>) permission on the table.
d1264 5
a1268 4
	  <literal>"joe=arwR"</literal>: User <literal>joe</literal> has read,
	  write (<command>UPDATE</command>, <command>DELETE</command>),
	  <quote>append</quote> (<command>INSERT</command>) permissions,
	  and permission to create rules on the table.
d1274 3
a1276 2
	  <literal>"group staff=ar"</literal>: Group <literal>staff</literal>
	  has <command>SELECT</command> and <command>INSERT</command> permission.
d1297 3
a1299 2
        <replaceable class="parameter">command</replaceable>. The arguments
        are not further interpreted, the shell will see them as is.
d1309 2
a1310 1
        Get help information about the backslash (<quote>\</quote>) commands.
d1329 3
a1331 3
  If so configured, <application>psql</application> understands both standard
  Unix short options, and <acronym>GNU</acronym>-style long options. The latter
  are not available on all systems.
d1340 4
a1343 3
      Print all the lines to the screen as they are read. This is more useful for
      script processing rather than interactive mode.
      This is equivalent to setting the variable <envar>ECHO</envar> to <literal>all</literal>.
d1353 2
a1354 2
      Switches to unaligned output mode. (The default output mode is otherwise
      aligned.)
d1364 3
a1366 3
      Specifies that <application>psql</application>
      is to execute one query string, <replaceable class="parameter">query</replaceable>,
      and then exit.  This is useful in shell scripts.
d1369 5
a1373 4
      <replaceable class="parameter">query</replaceable> must be either a query string
      that is completely parseable by the backend (i.e., it contains no <application>psql</application>
      specific features), or it is a single backslash command. Thus
      you cannot mix <acronym>SQL</acronym> and <application>psql</application>
d1375 2
a1376 2
      <application>psql</application>, like this:
      <literal>echo "\x \\ select * from foo;" | psql</literal>.
d1386 3
a1388 2
      Specifies the name of the database to connect to. This is equivalent to specifying
      <replaceable class="parameter">dbname</replaceable> as the first non-option
d1399 3
a1401 3
      Show all queries that are sent to the backend.
      This is equivalent to setting the variable <envar>ECHO</envar>
      to <literal>queries</literal>.
d1411 5
a1415 4
      Echoes the actual queries generated by \d and other backslash commands.
      You can use this if you wish to include similar functionality into
      your own programs. This is equivalent to setting the variable
      <envar>ECHO_HIDDEN</envar> from within <application>psql</application>.
d1427 3
a1429 2
      After the file is processed, <application>psql</application> terminates.
      This is in many ways equivalent to the internal command <command>\i</command>.
d1438 10
a1447 8
      Using this option is subtly different from writing
      <literal>psql &lt; <replaceable class="parameter">filename</replaceable></literal>.
      In general, both will do what you expect, but using <literal>-f</literal>
      enables some nice features such as error messages with line numbers.
      There is also a slight chance that using this option will reduce
      the start-up overhead. On the other hand, the variant using the shell's
      input redirection is (in theory) guaranteed to yield exactly the same
      output that you would have gotten had you entered everything by hand.
d1457 3
a1459 2
      Use <replaceable class="parameter">separator</replaceable> as the field separator.
      This is equivalent to <command>\pset fieldsep</command> or <command>\f</command>.
d1470 3
a1472 3
      <application>postmaster</application> is running.
      If host begins with a slash, it is used 
      as the directory for the unix domain socket.
d1482 3
a1484 3
      Turns on <acronym>HTML</acronym> tabular output. This is equivalent
      to <literal>\pset format html</literal> or the <command>\H</command>
      command.
d1494 3
a1496 2
      Lists all available databases, then exits. Other non-connection options
      are ignored. This is similar to the internal command <command>\list</command>.
d1506 3
a1508 2
      Put all query output into file <replaceable class="parameter">filename</replaceable>.
      This is equivalent to the command <command>\o</command>.
d1518 6
a1523 5
      Specifies the TCP/IP port or, by omission, the local Unix domain socket file
      extension on which the <application>postmaster</application>
      is listening for connections.  Defaults to the value of the
      <envar>PGPORT</envar> environment variable or, if not set, to the port
      specified at compile time, usually 5432.
d1533 5
a1537 4
      Allows you to specify printing options in the style of <command>\pset</command>
      on the command line. Note that here you have to separate name and value with
      an equal sign instead of a space. Thus to set the output format to LaTeX, you
      could write <literal>-P format=latex</literal>.
d1547 6
a1552 5
      Specifies that <application>psql</application> should do its work quietly.
      By default, it prints welcome messages and various informational output.
      If this option is used, none of this happens. This is useful with the
      <option>-c</option> option. Within <application>psql</application> you can
      also set the <envar>QUIET</envar> variable to achieve the same effect.
d1562 3
a1564 2
      Use <replaceable class="parameter">separator</replaceable> as the record separator.
      This is equivalent to the <command>\pset recordsep</command> command.
d1574 3
a1576 3
      Run in single-step mode. That means the user is prompted before each query
      is sent to the backend, with the option to cancel execution as well.
      Use this to debug scripts.
d1586 2
a1587 1
      Runs in single-line mode where a newline terminates a query, as a semicolon does.
d1592 4
a1595 4
      This mode is provided for those who insist on it, but you are not necessarily
      encouraged to use it. In particular, if you mix <acronym>SQL</acronym> and
      meta-commands on a line the order of execution might not always be clear to
      the inexperienced user.
d1606 3
a1608 2
      Turn off printing of column names and result row count footers, etc.
      It is completely equivalent to the <command>\t</command> meta-command.
d1618 3
a1620 2
      Allows you to specify options to be placed within the <acronym>HTML</acronym>
      <sgmltag>table</sgmltag> tag. See <command>\pset</command> for details.
d1630 2
a1631 2
      Makes <application>psql</application> prompt for the user name and password
      before connecting to the database.
d1635 5
a1639 4
      This option is deprecated, as it is conceptually flawed. (Prompting for
      a non-default user name and prompting for a password because the
      backend requires it are really two different things.) You are encouraged
      to look at the <option>-U</option> and <option>-W</option> options instead.
d1649 3
a1651 2
      Connects to the database as the user <replaceable class="parameter">username</replaceable>
      instead of the default. (You must have permission to do so, of course.)
d1662 6
a1667 7
      internal command.  Note that you must separate name and value,
      if any, by an equal sign on the command line. To unset a
      variable, leave off the equal sign.  To just set a variable
      without a value, use the equal sign but leave off the value.
      These assignments are done during a very early stage of
      start-up, so variables reserved for internal purposes might get
      overwritten later.
d1687 4
a1690 4
      Requests that <application>psql</application> should prompt for a password
      before connecting to a database. This will remain set for the entire
      session, even if you change the database connection with the meta-command
      <command>\connect</command>.
d1694 7
a1700 6
      In the current version, <application>psql</application> automatically issues a
      password prompt whenever the backend requests password authentication.
      Because this is currently based on a hack, the automatic
      recognition might mysteriously fail, hence this option to force a prompt.
      If no password prompt is issued and the backend requires password authentication
      the connection attempt will fail.
d1710 2
a1711 2
      Turns on extended row format mode. This is equivalent to the command
      <command>\x</command>.
d1731 2
a1732 1
      Shows help about <application>psql</application> command line arguments.
d1754 7
a1760 6
    <application>psql</application> provides variable substitution features
    similar to common Unix command shells. This feature is new and not very
    sophisticated, yet, but there are plans to expand it in the future.
    Variables are simply name/value
    pairs, where the value can be any string of any length. To set variables,
    use the <application>psql</application> meta-command <command>\set</command>:
d1764 4
a1767 3
    sets the variable <quote>foo</quote> to the value <quote>bar</quote>. To retrieve
    the content of the variable, precede the name with a colon and use it
    as the argument of any slash command:
d1776 10
a1785 9
    The arguments of <command>\set</command> are subject to the same substitution
    rules as with other commands. Thus you can construct interesting references
    such as <literal>\set :foo 'something'</literal> and get <quote>soft
    links</quote> or <quote>variable variables</quote> of <productname>Perl</productname>
    or <productname><acronym>PHP</acronym></productname> fame, respectively.
    Unfortunately (or fortunately?), there is no way to do anything useful
    with these constructs. On the
    other hand, <literal>\set bar :foo</literal> is a perfectly valid way to copy
    a variable.
d1790 3
a1792 3
    If you call <command>\set</command> without a second argument, the variable is simply
    set, but has no value. To unset (or delete) a variable, use the command
    <command>\unset</command>.
d1796 12
a1807 12
    <application>psql</application>'s internal variable names can consist of
    letters, numbers, and underscores in any order and any number of them.
    A number of regular variables are treated specially by <application>psql</application>.
    They indicate certain option settings that can be changed at run time
    by altering the value of the variable or represent some state of the application.
    Although you can use these
    variables for any other purpose, this is not recommended, as the
    program behavior might grow really strange really quickly.
    By convention, all specially treated variables consist of all upper-case letters
    (and possibly numbers and underscores). To ensure maximum compatibility in the
    future, avoid such variables. 
    A list of all specially treated variables follows.
d1813 3
a1815 2
        The name of the database you are currently connected to. This is set every time
        you connect to a database (including program start-up), but can be unset.
d1824 8
a1831 6
	If set to <quote><literal>all</literal></quote>, all lines entered or from a script
        are written to the standard output before they
	are parsed or executed. To specify this on program start-up, use the switch
        <option>-a</option>. If set to <quote><literal>queries</literal></quote>,
        <application>psql</application> merely prints all queries as they are sent to the
        backend. The option for this is <option>-e</option>.
d1840 7
a1846 5
	When this variable is set and a backslash command queries the database, the query
	is first shown. This way you can study the <productname>PostgreSQL</productname>
	internals and provide similar functionality in your own programs. If you set the
	variable to the value <quote>noexec</quote>, the queries are just shown but are
	not actually sent to the backend and executed.
d1855 2
a1856 2
        The current client multibyte encoding. If you are not set up to use
        multibyte characters, this variable will always contain
d1866 7
a1872 6
         If  this variable is set  to  <literal>ignorespace</literal>, lines which begin with a
         space are not entered into the history list. If set to a value of
         <literal>ignoredups</literal>, lines matching the previous history line are not
         entered. A value of <literal>ignoreboth</literal> combines the two
         options.  If unset, or if set to any other value than those above, all lines read
         in interactive mode are saved on the history list.
d1876 2
a1877 1
        This feature was shamelessly plagiarized from <application>bash</application>.
d1887 2
a1888 2
        The number of commands to store in the command history.
        The default value is 500.
d1892 2
a1893 1
        This feature was shamelessly plagiarized from <application>bash</application>.
d1903 3
a1905 2
        The database server host you are currently connected to. This is set every time
        you connect to a database (including program start-up), but can be unset.
d1914 6
a1919 4
         If unset, sending an EOF character (usually Control-D) to an interactive session of
         <application>psql</application> will terminate the application.
         If set to a numeric value, that many EOF characters are ignored before the application
         terminates. If the variable is set but has no numeric value, the default is 10.
d1923 2
a1924 1
        This feature was shamelessly plagiarized from <application>bash</application>.
d1934 5
a1938 4
        The value of the last affected oid, as returned from an <command>INSERT</command>
        or <command>lo_insert</command> command. This variable is only guaranteed to be
        valid until after the result of the next <acronym>SQL</acronym> command has been
        displayed.
d1947 16
a1962 14
	If you use the <productname>PostgreSQL</productname> large object
        interface to specially store data that does not fit into one tuple,
        all the operations must be contained in a transaction block. (See the
        documentation of the large object interface for more information.) Since
        <application>psql</application> has no way to tell if you already
        have a transaction in progress when you call one of its internal
        commands (<command>\lo_export</command>, <command>\lo_import</command>,
        <command>\lo_unlink</command>) it must take some arbitrary action. This
        action could either be to roll back any transaction that might already
        be in progress, or to commit any such transaction, or to do nothing at
        all. In the last case you must provide your own
        <command>BEGIN TRANSACTION</command>/<command>COMMIT</command> block or
        the results will be unpredictable (usually resulting in the desired
        action's not being performed in any case).
d1967 6
a1972 5
	<quote>rollback</quote>, <quote>commit</quote>, or <quote>nothing</quote>.
        The default is to roll back the transaction. If you just want to load one
        or a few objects this is fine. However, if you intend to transfer many
        large objects, it might be advisable to provide one explicit transaction
        block around all commands.
d1981 12
a1992 10
	By default, if non-interactive scripts encounter an error, such as a
	malformed <acronym>SQL</acronym> query or internal meta-command,
	processing continues. This has been the traditional behavior of
        <application>psql</application> but it is sometimes not desirable. If this variable
	is set, script processing will immediately terminate. If the script was
	called from another script it will terminate in the same fashion.
	If the outermost script was not called from an interactive <application>psql</application>
	session but rather using the <option>-f</option> option, <application>psql</application>
	will return error code 3, to distinguish this case from fatal
	error conditions (error code 1).
d2001 3
a2003 2
        The database server port to which you are currently connected. This is set every time
        you connect to a database (including program start-up), but can be unset.
d2012 4
a2015 4
	These specify what the prompt <application>psql</application> issues is
	supposed to look like. See
	<quote><xref linkend="APP-PSQL-prompting" endterm="APP-PSQL-prompting-title"></quote>
	below.
d2024 3
a2026 2
	This variable is equivalent to the command line option <option>-q</option>.
	It is probably not too useful in interactive mode.
d2035 2
a2036 2
	This variable is set by the command line option <option>-S</option>. You
	can unset or reset it at run time.
d2045 2
a2046 1
	This variable is equivalent to the command line option <option>-s</option>.
d2055 3
a2057 2
        The database user you are currently connected as. This is set every time
        you connect to a database (including program start-up), but can be unset.
d2073 5
a2077 4
    An additional useful feature of <application>psql</application> variables
    is that you can substitute (<quote>interpolate</quote>) them into
    regular <acronym>SQL</acronym> statements. The syntax for this is again to prepend
    the variable name with a colon (<literal>:</literal>).
d2082 5
a2086 5
    would then query the table <literal>my_table</literal>. The value of the
    variable is copied literally, so it can even contain unbalanced quotes or
    backslash commands. You must make sure that it makes sense where you put it.
    Variable interpolation will not be performed into quoted <acronym>SQL</acronym>
    entities.
d2090 5
a2094 5
    A popular application of this facility is to refer to the last inserted
    <acronym>OID</acronym> in subsequent statements to build a foreign key
    scenario.
    Another possible use of this mechanism is to copy the contents of a file
    into a field. First load the file into a variable and then proceed as above.
d2106 14
a2119 12
    Observe the correct number of backslashes (6)! You can resolve it this way: After
    <application>psql</application> has parsed this line, it passes
    <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal> to the shell. The shell
    will do its own thing inside the double quotes and execute <filename>sed</filename>
    with the arguments <literal>-e</literal> and <literal>s/'/\\'/g</literal>.
    When <application>sed</application> parses this it will replace the two
    backslashes with a single one and then do the substitution. Perhaps at
    one point you thought it was great that all Unix commands use the same
    escape character. And this is ignoring the fact that you might have to
    escape all backslashes as well because <acronym>SQL</acronym> text constants
    are also subject to certain interpretations. In that case you might
    be better off preparing the file externally.
d2123 9
a2131 7
    Since colons may legally appear in queries, the following rule applies: If the variable
    is not set, the character sequence <quote>colon+name</quote> is not changed. In any
    case you can escape a colon with a backslash to protect it from interpretation.
    (The colon syntax for variables is standard <acronym>SQL</acronym> for embedded
    query languages, such as <application>ecpg</application>. The colon syntax for
    array slices and type casts are <productname>PostgreSQL</productname> extensions,
    hence the conflict.)
d2141 11
a2151 9
    The prompts <application>psql</application> issues can be customized to
    your preference. The three variables <envar>PROMPT1</envar>, <envar>PROMPT2</envar>,
    and <envar>PROMPT3</envar> contain strings and special escape sequences
    that describe the appearance of the prompt. Prompt 1 is the normal prompt
    that is issued when <application>psql</application> requests a new query.
    Prompt 2 is issued when more input is expected during query input because
    the query was not terminated with a semicolon or a quote was not closed.
    Prompt 3 is issued when you run an <acronym>SQL</acronym> <command>COPY</command>
    command and you are expected to type in the tuples on the terminal.
d2155 4
a2158 3
    The value of the respective prompt variable is printed literally, except where
    a percent sign (<quote>%</quote>) is encountered. Depending on the next
    character, certain other text is substituted instead. Defined substitutions are:
d2166 4
a2169 4
          or <literal>[local]</literal> if the connection is over a
          Unix domain socket, or
          <literal>[local:<replaceable>/dir/name</replaceable>]</literal>,
          if the Unix domain socket is not at the compiled in default
d2180 2
a2181 2
          first dot, or <literal>[local]</literal> if the connection
          is over a Unix domain socket.
d2216 13
a2228 9
	<listitem><para>
	In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if in single-line
        mode, and <quote>!</quote> if the session is disconnected from the database
        (which can happen if <command>\connect</command> fails). In prompt 2 the
        sequence is replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
	or a double quote, depending on whether <application>psql</application>
        expects more input because the query wasn't terminated yet, because you are
        inside a <literal>/* ... */</literal> comment, or because you are inside
        a quote. In prompt 3 the sequence doesn't resolve to anything.</para>
d2234 10
a2243 7
	<listitem><para>
	If <replaceable class="parameter">digits</replaceable> starts with
        <literal>0x</literal> the rest of the characters are interpreted as a
        hexadecimal digit and the character with the corresponding code is
        substituted. If the first digit is <literal>0</literal> the characters are
        interpreted as on octal number and the corresponding character is
        substituted. Otherwise a decimal number is assumed.</para>
d2249 7
a2255 5
	<listitem><para>
	The value of the <application>psql</application>, variable <replaceable
        class="parameter">name</replaceable>. See the section
	<quote><xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title"></quote>
	for details.</para>
d2261 6
a2266 3
	<listitem><para>
	The output of <replaceable class="parameter">command</replaceable>, similar to
	ordinary <quote>back-tick</quote> substitution.</para>
d2272 4
a2275 3
    To insert a percent sign into your prompt, write <literal>%%</literal>. The
    default prompts are equivalent to <literal>'%/%R%# '</literal> for prompts 1
    and 2, and <literal>'&gt;&gt; '</literal> for prompt 3.
d2280 2
a2281 1
    This feature was shamelessly plagiarized from <application>tcsh</application>.
d2291 5
a2295 5
    <application>psql</application> returns 0 to the shell if it finished normally,
    1 if a fatal error of its own (out of memory, file not found) occurs, 2 if the
    connection to the backend went bad and the session is not interactive, and 3 if
    an error occurred in a script and the variable <envar>ON_ERROR_STOP</envar> was
    set.
d2299 5
a2303 4
    Before starting up, <application>psql</application> attempts
    to read and execute commands from the file <filename>$HOME/.psqlrc</filename>. It
    could be used to set up the client or the server to taste (using the <command>\set
    </command> and <command>SET</command> commands).
d2312 11
a2322 10
    <application>psql</application> supports the readline and history libraries for
    convenient line editing and retrieval. The command history is stored in a file
    named <filename>.psql_history</filename> in your home directory and is reloaded when
    <application>psql</application> starts up.
    Tab-completion is also supported, although
    the completion logic makes no claim to be an <acronym>SQL</acronym> parser.
    When available, <application>psql</application> is automatically built to use these
    features. If for some reason you do not like the tab completion, you can turn if off
    by putting this in a file named <filename>.inputrc</filename> in your
    home directory:
d2328 3
a2330 2
    (This is not a <application>psql</application> but a <application>readline</application>
    feature. Read its documentation for further details.)
d2334 13
a2346 10
    If you have the readline library installed but <application>psql</application>
    does not seem to use it, you must make sure that <productname>PostgreSQL</productname>'s
    top-level <filename>configure</filename> script finds it. <filename>configure</filename>
    needs to find both the library <filename>libreadline.a</filename>
    (or a shared library equivalent)
    <emphasis>and</emphasis> the header files <filename>readline.h</filename> and
    <filename>history.h</filename> (or <filename>readline/readline.h</filename> and
    <filename>readline/history.h</filename>) in appropriate directories. If
    you have the library and header files installed in an obscure place you
    must tell <filename>configure</filename> about them, for example:
d2350 2
a2351 2
    Then you have to recompile <application>psql</application> (not necessarily
    the entire code tree).
d2355 3
a2357 2
    The <acronym>GNU</acronym> readline library can be obtained from the <acronym>GNU</acronym>
    project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
d2371 5
a2375 4
  This section only shows a few examples specific to <application>psql</application>.
  If you want to learn <acronym>SQL</acronym> or get familiar with
  <productname>PostgreSQL</productname>, you might wish to read the Tutorial that
  is included in the distribution.
d2380 2
a2381 2
  The first example shows how to spread a query over several lines of input.
  Notice the changing prompt:
d2405 2
a2406 1
  Let's assume you have filled the table with data and want to take a look at it:
d2418 2
a2419 2
  You can make this table look differently by using the <command>\pset</command>
  command:
d2497 6
a2502 5
      In some earlier life <application>psql</application> allowed the first
      argument to start directly after the (single-letter) command. For
      compatibility this is still supported to some extent but I am not
      going to explain the details here as this use is discouraged. But
      if you get strange messages, keep this in mind. For example
d2513 4
a2516 3
      <application>psql</application> only works smoothly with servers of the
      same version. That does not mean other combinations will fail outright,
      but subtle and not-so-subtle problems might come up.
d2522 5
a2526 4
      Pressing Control-C during a <quote>copy in</quote> (data sent to the
      server) doesn't show the most ideal of behaviors. If you get a message
      such as <quote>COPY state must be terminated first</quote>,
      simply reset the connection by entering <literal>\c - -</literal>.
@


1.65
log
@Code review for DOMAIN patch.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.64 2002/03/19 02:32:19 momjian Exp $
d69 1
a69 1
    name of your target database, the hostname and port number of the server
d80 1
a80 1
    cases. The default user name is your Unix username, as is the default
d82 1
a82 1
    Note that you can't just connect to any database under any username. Your database
d273 1
a273 1
	If the connection attempt failed (wrong username, access denied, etc.), the
d1704 1
a1704 1
    They indicate certain option settings that can be changed at runtime
d2040 1
a2040 1
          The full hostname (with domain name) of the database server,
d2054 1
a2054 1
          The hostname of the database server, truncated after the
d2068 1
a2068 1
	<listitem><para>The username you are connected as (not your local system
@


1.64
log
@Add psql \dD listing of domains, from Jonathan Eisler.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.63 2002/03/11 05:03:52 petere Exp $
d422 3
a424 12
        Lists all database domains.
        </para>

        <para>
        Descriptions for objects can be generated with the <command>COMMENT ON</command>
        <acronym>SQL</acronym> command.
	</para>

        <note>
        <para>
        <productname>PostgreSQL</productname> stores the object descriptions in the
        pg_description system table.
a425 2
        </note>

@


1.63
log
@Fix markup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.62 2002/03/05 00:00:58 momjian Exp $
d400 23
@


1.62
log
@Add \timing patch to psql.  Times all queries.

Greg Sabino Mullane
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.61 2001/12/08 03:24:38 thomas Exp $
d1123 1
a1123 1
        <term><literal>\timing</literal>
d1126 1
a1126 1
        Toggles a display of how long each query takes in seconds.
d1128 1
a1128 1
        </listitem>
@


1.61
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/psql-ref.sgml,v 1.60 2001/09/13 15:55:24 petere Exp $
d1117 10
@


1.60
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 2
a3 2
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.59 2001/09/11 05:11:59 ishii Exp $
Postgres documentation
d40 2
a41 2
     <productname>Postgres</productname>. It enables you to type in queries
     interactively, issue them to <productname>Postgres</productname>, and see
d67 1
a67 1
    <application>psql</application> is a regular <productname>Postgres</productname>
d337 1
a337 1
        Shows the copyright and distribution terms of <application>Postgres</application>.
d409 1
a409 1
        <productname>Postgres</productname> stores the object descriptions in the
d665 1
a665 1
        for the databases as well. If your <productname>Postgres</productname>
d705 1
a705 1
	Stores the file into a <productname>Postgres</productname> <quote>large object</quote>.
d737 1
a737 1
	Shows a list of all <productname>Postgres</productname> <quote>large
d1721 1
a1721 1
	is first shown. This way you can study the <productname>Postgres</productname>
d1817 1
a1817 1
	If you use the <productname>Postgres</productname> large object
d1986 1
a1986 1
    array slices and type casts are <productname>Postgres</productname> extensions,
d2171 1
a2171 1
    does not seem to use it, you must make sure that <productname>Postgres</productname>'s
d2205 1
a2205 1
  <productname>Postgres</productname>, you might wish to read the Tutorial that
@


1.59
log
@Add single quote (example given here does not work)
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.58 2001/09/03 12:57:50 petere Exp $
d106 1
a106 1
    connected, followed by the string "=>". For example,
d1155 1
a1155 1
test=> <userinput>\z</userinput>
@


1.58
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/psql-ref.sgml,v 1.57 2001/07/15 13:45:03 petere Exp $
d1964 1
a1964 1
testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinput>
@


1.57
log
@NLS for libpq.  Clean up the message formats and change the documentation
accordingly.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.56 2001/06/10 03:46:31 momjian Exp $
d20 1
a20 1
      <productname>Postgres</productname> interactive terminal
@


1.56
log
@Update or remove mentions of versions where appropriate.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.55 2001/05/28 04:27:17 momjian Exp $
d2352 1
a2352 1
      such as <quote>PQexec: you gotta get out of a COPY state yourself</quote>,
@


1.55
log
@Sample output that appears below the table attributes for \d:

Indicies: palm_buy_date_idx
          palm_user_date_idx
Primary Key: palm_buyers_pkey
Unique Key: palm_buyers_username
Constraint: "$1" ((sex = 'M'::bpchar) OR (sex = 'F'::bpchar))

Note that check constraint name now shown as well.  (Makes it a lot easier
to test inheritance support in ADD/DROP constraint :) )

Attached is a docs change for psql.

Christopher Kings
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.54 2001/05/27 09:59:28 petere Exp $
d1054 1
a1054 1
	As of <application>psql</application> version 7.0 it is no longer
d1582 1
a1582 1
      As of version 7.0, <application>psql</application> automatically issues a
@


1.54
log
@Make UPDATE and DELETE privileges distinct.  Add REFERENCES and TRIGGER
privileges.  INSERT and COPY FROM now require INSERT (only).  Add
privileges regression test.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.53 2001/05/17 21:50:18 petere Exp $
d351 2
a352 1
	If the relation is, in fact, a table, any defined indexes are also listed.
@


1.53
log
@Change "indices" to "indexes", per OED.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.52 2001/05/12 19:44:45 petere Exp $
d1190 2
a1191 2
	The commands <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
	<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">
@


1.52
log
@Add command '\pset footer' to psql to turn off default "(x rows)" footer.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.51 2001/05/09 17:29:10 momjian Exp $
d351 1
a351 1
	If the relation is, in fact, a table, any defined indices are also listed.
d390 1
a390 1
        (tables, views, indices, sequences, large objects), rules, and triggers.) For example:
@


1.51
log
@
Here's a version of my suggested diffs transplanted to 7.1 beta 5.  I'm
still looking at the best way to integrate Tom Vijlbrief's fixes
(insofar as they're still needed); would 7.2 be a suitable time for
incompatible API changes?


Jeroen


Changes:

(*) Introduced bool, true, false (replacing some int, 1, 0)
(*) Made some member functions const
(*) Documented GetIsNull()
(*) Marked DisplayTuples() and PrintTuples() as obsolescent; fixed possible
    portability problem (assumed that NULL pointer equals all-zero bit pattern)
(*) PrintTuples(): renamed width parameter to fillAlign to conform with other
    usage; fixed memory leak and compile issue w.r.t. field separator (should
    also slightly improve performance)
(*) Fixed some minor compilation issues
(*) Moved "using namespace std;" out of headers, where they didn't belong; used
    new (temporary) preprocessor macro PGSTD to do this
(*) Made ToString() static, removed unneeded memset(), made buffer size adapt
    to sizeof(int)
(*) Made some constructors explicit
(*) Changed some const std::string & parameters to plain std::string
(*) Marked PgCursor::Cursor(std::string) as obsolescent (setter with same name
    as getter--bad style)
(*) Renamed some paramaters previously named "string"
(*) Introduced size_type typedef for number of tuples in result set
(*) PgTransaction now supports re-opening after closing, and aborts if not
    explicitly committed prior to destruction

J. T. Vermeulen
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.50 2001/05/07 19:31:33 petere Exp $
d897 9
@


1.50
log
@Add \cd command to psql.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.49 2001/05/06 17:38:31 petere Exp $
d492 10
@


1.49
log
@Allow 'psql -f -' to read from standard input.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.48 2001/05/06 17:21:11 petere Exp $
d218 17
@


1.48
log
@Make prompt customization work with changeable Unix socket location.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.47 2001/03/24 23:03:26 petere Exp $
d1295 6
@


1.47
log
@minor copy editing
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.46 2001/02/03 19:09:46 petere Exp $
d1973 10
a1982 2
	<listitem><para>The full hostname (with domain name) of the database server (or
         <quote>localhost</quote> if hostname information is not available).</para></listitem>
d1987 7
a1993 2
	<listitem><para>The hostname of the database server, truncated after the
         first dot.</para></listitem>
@


1.46
log
@Improved wording, from Albert REINER <areiner@@tph.tuwien.ac.at>.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.45 2000/12/25 23:15:26 petere Exp $
d1926 1
a1926 1
    will do it's own thing inside the double quotes and execute <filename>sed</filename>
@


1.45
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/psql-ref.sgml,v 1.44 2000/11/22 01:41:13 momjian Exp $
d1505 8
a1512 5
      Performs a variable assignment, like the <command>\set</command> internal command.
      Note that you must separate name and value, if any, by an equal sign on the command
      line. To unset a variable, leave off the equal sign. These assignments are done
      during a very early state of start-up, so variables reserved for internal purposes
      might get overwritten later.
@


1.44
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/psql-ref.sgml,v 1.43 2000/11/13 23:57:20 momjian Exp $
d7 4
d12 2
a13 3
    <refentrytitle id="app-psql-title">
        <application>psql</application>
    </refentrytitle>
d18 1
a18 3
    <refname>
      <application>psql</application>
    </refname>
@


1.43
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/psql-ref.sgml,v 1.42 2000/11/13 23:37:51 momjian Exp $
d1326 1
a1326 1
      as the path to a unix domain socket.
@


1.42
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/psql-ref.sgml,v 1.41 2000/11/13 15:18:08 momjian Exp $
d1325 2
a1326 2
      Without this option, communication is performed using
      local Unix domain sockets.
@


1.41
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/psql-ref.sgml,v 1.40 2000/10/24 01:38:21 tgl Exp $
a1326 13
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
      <term>-k, --unixsocket <replaceable class="parameter">path</replaceable></term>
      <listitem>
      <para>
      Specifies the Unix-domain socket on which the
      <application>postmaster</application> is running.
      Without this option, the socket is created in <filename>/tmp</filename>
      based on the port number.
@


1.40
log
@Major overhaul of large-object implementation, by Denis Perchine with
kibitzing from Tom Lane.  Large objects are now all stored in a single
system relation "pg_largeobject" --- no more xinv or xinx files, no more
relkind 'l'.  This should offer substantial performance improvement for
large numbers of LOs, since there won't be directory bloat anymore.
It'll also fix problems like running out of locktable space when you
access thousands of LOs in one transaction.
Also clean up cruft in read/write routines.  LOs with "holes" in them
(never-written byte ranges) now work just like Unix files with holes do:
a hole reads as zeroes but doesn't occupy storage space.
INITDB forced!
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.39 2000/10/12 22:16:58 momjian Exp $
d1327 13
@


1.39
log
@Fix typo
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.38 2000/10/05 19:48:18 momjian Exp $
d709 2
a710 1
	objects</quote> currently stored in the database along with their owners.
@


1.38
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/psql-ref.sgml,v 1.37 2000/09/27 11:56:16 momjian Exp $
d1968 1
a1968 1
	<listitem><para>The full hostname (with domainname) of the database server (or
@


1.37
log
@Change with delimiters to using delimiters in psql manual page.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.36 2000/08/29 20:02:09 momjian Exp $
d75 1
a75 1
    If you omit the host name psql will connect via a UNIX domain socket
d156 2
a157 2
    are separated from the command verb and each other by any number of white
    space characters.
d255 1
a255 1
	If the connection attempt failed (wrong username, access denied, etc.) the
d408 1
a408 1
        each function, including language and description is shown.
d427 1
a427 1
	it is a regular expression restricts the listing to those objects
d744 1
a744 1
	<replaceable class="parameter">filename</replaceable> or pipe future
d1177 1
a1177 1
        Get help information about the slash (<quote>\</quote>) commands.
d1291 1
a1291 1
      This in many ways equivalent to the internal command <command>\i</command>.
d1775 2
a1776 2
        commands <command>\lo_export</command>, <command>\lo_import</command>,
        <command>\lo_unlink</command> it must take some arbitrary action. This
d1903 1
a1903 1
    <acronym>OID</acronym> in subsequent statement to build a foreign key
d2024 1
a2024 1
        <literal>0x</literal> the rest of the characters are interpreted at a
a2186 1
  Notice how the int4 columns in right aligned while the text column in left aligned.
d2273 1
a2273 1
Field separator is "oo".
d2275 1
a2275 1
      is perhaps not what one would expect.
@


1.36
log
@Startup is actually start-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.35 2000/07/22 04:45:09 momjian Exp $
d269 1
a269 1
        [ <literal>with delimiters</literal> '<replaceable class="parameter">characters</replaceable>' ]
@


1.35
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.34 2000/07/21 17:58:49 momjian Exp $
d1299 1
a1299 1
      the startup overhead. On the other hand, the variant using the shell's
d1506 1
a1506 1
      during a very early state of startup, so variables reserved for internal purposes
d1560 1
a1560 1
      Do not read the startup file <filename>~/.psqlrc</filename>.
d1649 1
a1649 1
        you connect to a database (including program startup), but can be unset.
d1660 1
a1660 1
	are parsed or executed. To specify this on program startup, use the switch
d1731 1
a1731 1
        you connect to a database (including program startup), but can be unset.
d1819 1
a1819 1
        you connect to a database (including program startup), but can be unset.
d1870 1
a1870 1
        you connect to a database (including program startup), but can be unset.
@


1.34
log
@More doc cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.33 2000/05/12 00:54:52 momjian Exp $
d1648 1
a1648 1
        The name of the database you are currently connected to. This is set everytime
d1730 1
a1730 1
        The database server host you are currently connected to. This is set everytime
d1758 1
a1758 1
        or <command>lo_insert</command> commmand. This variable is only guaranteed to be
d1802 1
a1802 1
	processing continues. This has been the traditional behaviour of
d2026 1
a2026 1
        subsituted. If the first digit is <literal>0</literal> the characters are
d2187 1
a2187 1
  Notice how the int4 colums in right aligned while the text column in left aligned.
d2282 1
a2282 1
      <application>psql</application> only works smootly with servers of the
d2291 1
a2291 1
      server) doesn't show the most ideal of behaviours. If you get a message
@


1.33
log
@Small cleanup of file.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.32 2000/05/09 18:55:56 momjian Exp $
d494 2
a495 2
        a single line. (Thus you cannot make <quote>scripts</quote> this way,
        use <command>\i</command> for that.) This means also that
d554 2
a555 2
        Sets the field separator for unaligned query output. The default is <quote><literal>|</literal></quote>
	(a <quote>pipe</quote> symbol). See also <command>\pset</command> for a generic way
d1536 1
a1536 1
      Because this is currently based on a <quote>hack</quote>, the automatic
d2151 1
a2151 1
  Notice the changing prompt.
d2189 1
a2189 1
  command.
@


1.32
log
@Fix psql quotes in docs.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.31 2000/04/16 15:46:39 petere Exp $
d1617 1
a1617 1
    Unfortunately (or fortunately?), there is not way to do anything useful
@


1.31
log
@more psql bug squashing:
\copy without arguments failed
commands with too many arguments were too silent
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.30 2000/03/27 17:14:43 thomas Exp $
d854 1
a854 1
	  <literal>\pset null "(null)"</literal>.
d866 2
a867 2
	  <literal>\pset fieldsep "\t"</literal>. The default field separator is
	  <quote><literal>|</literal></quote> (a <quote>pipe</quote> symbol).
d2154 2
a2155 2
testdb-> <userinput> first integer not null default 0,</userinput>
testdb-> <userinput> second text</userinput>
@


1.30
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/psql-ref.sgml,v 1.29 2000/03/21 01:52:12 momjian Exp $
d446 1
a446 1
        <term><literal>\do [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
d450 1
a450 1
        If <replaceable class="parameter">pattern</replaceable>
a451 4
        (Since this is a regular expression, be sure to quote all special
        characters in you operator name with backslashes. To prevent
        interpretation of the backslash as a new command, you might also
        wish to quote the argument.)
@


1.29
log
@This patch corrects spelling, grammar and euphony for the psql reference
page for 7.0:

Oliver Elphick
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.28 2000/03/11 13:56:23 petere Exp $
d19 1
a19 1
      <productname>PostgreSQL</productname> interactive terminal
d39 2
a40 2
     <productname>PostgreSQL</productname>. It enables you to type in queries
     interactively, issue them to <productname>PostgreSQL</productname>, and see
d66 1
a66 1
    <application>psql</application> is a regular <productname>PostgreSQL</productname>
d319 1
a319 1
        Shows the copyright and distribution terms of <application>PostgreSQL</application>.
d390 1
a390 1
        <productname>PostgreSQL</productname> stores the object descriptions in the
d640 1
a640 1
        for the databases as well. If your <productname>PostgreSQL</productname>
d680 1
a680 1
	Stores the file into a <productname>PostgreSQL</productname> <quote>large object</quote>.
d712 1
a712 1
	Shows a list of all <productname>PostgreSQL</productname> <quote>large
d1677 1
a1677 1
	is first shown. This way you can study the <productname>PostgreSQL</productname>
d1773 1
a1773 1
	If you use the <productname>PostgreSQL</productname> large object
d1942 1
a1942 1
    array slices and type casts are <productname>PostgreSQL</productname> extensions,
d2114 1
a2114 1
    does not seem to use it, you must make sure that <productname>PostgreSQL</productname>'s
d2148 1
a2148 1
  <productname>PostgreSQL</productname>, you might wish to read the Tutorial that
@


1.28
log
@Karel Zakr's revised patch to fix psql prompt for local host connections.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.27 2000/03/01 21:09:56 petere Exp $
d73 4
a76 2
    as database name as well. Not all these options are required, defaults do apply.
    If you omit the host name psql will connect via domain sockets to a server on the
d78 3
a80 2
    server uses the same default, chances are you don't have to specify the port in most
    settings. The default user name is your Unix username, the same with the database.
d84 2
a85 2
    <envar>PGHOST</envar>, <envar>PGPORT</envar>, <envar>PGUSER</envar>,
    respectively to appropriate values.
d104 2
a105 2
    the name of the database that <application>psql</application> is currently
    connected to followed by the string "=>". For example,
d124 1
a124 1
    can be spread over serveral lines for clarity. If the query was sent and without
d147 1
a147 1
    processes by <application>psql</application> itself.
d162 1
a162 1
    quote. To include a single quote into such an argument, preceed it by
d277 1
a277 1
        but instead of the backend reading or writing the specified file, and 
d281 1
a281 1
        file and routes the data to or from the backend onto the local file system.
d285 3
a287 3
	The syntax of the command is in analogy to the <acronym>SQL</acronym>
	<command>COPY</command> command, see its description for the details.
	Note that because of this, special parsing rules apply to the
d304 1
a304 1
        between frontend and backend copies: In a frontend copy these always refer
d306 2
a307 2
        copy <literal>stdin</literal> comes from whereever the <command>COPY</command>
        itself came from (for example, a script ran with the <option>-f</option>) option,
d489 1
a489 1
        the file is edited and after the editor exit its content is copied
d846 1
a846 1
	  Expanded mode is support by all four output modes.
d919 1
a919 1
	  Allows you to specify any attributes to be places inside the <acronym>HTML</acronym>
d1020 3
a1022 3
	necessary, in fact, to save the command history as that will be done
	automatically on program termination. The history is then
	also automatically loaded every time <application>psql</application>
d1038 1
a1038 1
	is given, the variable is just set with not value. To unset a variable, use
d1048 2
a1049 2
	Although you are welcome to set any variable to anything you want to,
	<application>psql</application> treats several variables special.
d1243 2
a1244 2
      meta-commands. To achieve this you could pipe the string into
      <application>psql</application>, like so:
d1279 1
a1279 1
      Echos the actual queries generated by \d and other backslash commands.
d1437 1
a1437 1
      Runs in single-line mode where a newline terminates a query, like a semicolon would do.
d1445 1
a1445 1
      the unexperienced user.
d1457 1
a1457 1
      It is completely equivalent to the <command>\t</command>.
d1511 1
a1511 1
      might get overwritten again.
d1777 1
a1777 1
        <application>psql</application> has no way to keep track if you already
d1783 1
a1783 1
        all. In the latter case you must provide you own
d1786 1
a1786 1
        action not being performed in any case).
d1806 1
a1806 1
	processing continues. This is has been the traditional behaviour of
d1822 1
a1822 1
        The database server port you are currently connected to. This is set everytime
d1854 1
a1854 1
	This variable is set be the command line options <option>-S</option>. You
d1873 1
a1873 1
        The database user you are currently connected as. This is set everytime
d1978 1
a1978 1
	<listitem><para>The hostname of the database server truncated after the
@


1.27
log
@More fixes for psql ^C handling, especially during copy. Still doesn't
cope so well with copy to but that will have to wait for the next release.

Also added -X option to prevent reading .psqlrc startup file.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.26 2000/02/20 14:29:21 petere Exp $
d1969 2
a1970 2
	<listitem><para>The hostname of the database server (or <quote>.</quote>
         if Unix domain socket).</para></listitem>
@


1.26
log
@Forgot to include the documentation for \encoding ...
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.25 2000/02/13 21:45:13 petere Exp $
d1558 10
d2078 1
a2078 1
    Before starting up in interactive mode, <application>psql</application> attempts
d2114 1
a2114 1
    (or <filename>libreadline.so</filename> on systems with shared libraries)
d2286 9
@


1.25
log
@Adjusted psql echoing options (-a and -e)
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.24 2000/02/10 20:08:55 petere Exp $
d539 12
d1668 11
@


1.24
log
@Default argument for createdb
Changed EXIT_ON_ERROR to ON_ERROR_STOP in psql
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.23 2000/02/07 23:10:03 petere Exp $
d612 1
a612 1
	the variable <envar>ECHO</envar> to <literal>full</literal>.
d1193 12
d1249 1
a1249 1
      <term>-e, --echo</term>
d1252 3
a1254 2
      In non-interactive mode, all lines are printed to the screen as they are read.
      This is equivalent to setting the variable <envar>ECHO</envar> to <literal>full</literal>.
d1637 1
a1637 1
	If set to <quote><literal>full</literal></quote>, all lines entered or from a script
d1639 4
a1642 4
	are parsed or executed. To specify this on program startup, in conjunction with the
	<option>-f</option> option perhaps, use the switch <option>-e</option>.
        If set to <quote><literal>brief</literal></quote>, <application>psql</application>
        merely prints all queries as they are sent to the backend.
@


1.23
log
@Fixed psql double quoting of SQL ids
Fixed libpq printing functions
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.22 2000/01/29 16:58:27 petere Exp $
a1647 18
        <term><envar>EXIT_ON_ERROR</envar></term>
	<listitem>
	<para>
	By default, if non-interactive scripts encounter an error, such as a
	malformed <acronym>SQL</acronym> query or internal meta-command,
	processing continues. This is has been the traditional behaviour of
        <application>psql</application>but is often less than desirable. If this variable
	is set, script processing will immediately terminate. If the script was
	called from another script it will terminate in the same fashion.
	If the outermost script was not called from an interactive <application>psql</application>
	session but rather using the <option>-f</option> option, <application>psql</application>
	will return error code 3, to distinguish this case from fatal
	error conditions (error code 1).
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
d1752 18
d1889 1
a1889 1
    is not set, the character sequence <quote>colon name</quote> is not changed. In any
d1990 2
a1991 2
	The value of the <application>psql</application>, <quote>magic</quote>, or environment
	variable <replaceable class="parameter">name</replaceable>. See the section
d2027 1
a2027 1
    an error occurred in a script and the variable <envar>EXIT_ON_ERROR</envar> was
@


1.22
log
@A few minor psql enhancements
Initdb help correction
Changed end/abort to commit/rollback and changed related notices
Commented out way old printing functions in libpq
Fixed a typo in alter table / alter column
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.21 2000/01/18 23:30:19 petere Exp $
d67 2
a68 2
    client application. In order to connect to a database you need to determine
    name of you target database, the hostname and port number of the server
d122 1
a122 1
    error the query results are displayed on the screen.
d158 5
a162 6
    To include whitespace into an argument you must quote it with either single
    or double quotes. Anything contained in single quotes (except for a
    backslash-escaped single quote itself) is taken literally as the argument.
    Anything contained in double quotes is furthermore subject to C-like
    substitutions for <literal>\n</literal> (new line), <literal>\t</literal> (tab),
    <literal>\</literal><replaceable>digits</replaceable>,
d169 1
a169 1
    If an unquoted argument begins with a dollar sign (<literal>$</literal>),
d171 1
a171 3
    argument instead. Inside double quotes, variable values can be substituted
    by enclosing the name in a <literal>${...}</literal> sequence. See also under
    <quote><xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title"></quote>.
d175 12
a186 5
    Arguments that are quoted in <quote>back-ticks</quote> (<literal>`</literal>)
    are taken as a command line
    that is passed to the shell. The output of the command (with a trailing
    newline removed) is taken as the argument value. Back-ticks are subject to
    the same substitution rules as double-quotes.
d196 1
a196 1
    In any case, the arguments of a meta-command cannot continue beyond the end
d253 1
a253 1
	previous connection will be kept, if and only if <application>psql</application> is
d293 1
a293 1
	client/server IP or socket connection. For large amounts of data this other
d517 2
a518 1
        Prints the arguments to the standard output. This can be useful to
d524 2
d612 1
a612 1
	the variable <envar>echo</envar>.
d668 1
a668 1
foo=> <userinput>\lo_import '/home/me/pictures/photo.xcf' 'a picture of me'</userinput>
d1016 1
a1016 1
        <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> ]]</term>
d1021 2
a1022 1
	to <replaceable class="parameter">value</replaceable>. If no second argument
d1156 1
a1156 3
        are not further interpreted, the shell will see them as is. If you wish
        to capture the output of a shell command and/or use <application>psql</application>'s
        variable substitution features, use the backticks (<literal>`</literal>).
d1209 1
a1209 1
      and then exit.  This is useful for shell scripts.
d1217 2
a1218 2
      <application>psql</application> and finish it with a a <literal>\q</literal>,
      like so: <literal>echo "select * from foo; \q" | psql</literal>.
d1269 10
a1330 10
      <term>-n, --no-readline</term>
      <listitem>
      <para>
      Do not use readline for line editing and do not use the history.
      </para>
      </listitem>
    </varlistentry>


    <varlistentry>
d1381 11
d1512 1
a1512 1
      Because this is currently based on a <quote>hack</quote> the automatic
d1559 3
a1561 1
    similar to common Unix command shells. Variables are simply name/value
d1568 1
a1568 1
    the content of the variable, precede the name with a dollar-sign and use it
d1571 1
a1571 1
testdb=> <userinput>\echo $foo</userinput>
a1573 9
    Alternatively, the value can also be interpolated into a double-quoted (or backtick-quoted)
    string, like so:
<programlisting>
testdb=> <userinput>\echo "foo is now ${foo}."</userinput>
foo is now bar.
</programlisting>
    (The curly braces are required.) No variable substitution
    will be performed in single-quoted strings or in any of the backslash commands
    that have special parsing rules (e.g., <command>\copy</command>).
d1580 1
a1580 1
    such as <literal>\set "${foo}bar" 'something'</literal> and get <quote>soft
d1584 2
a1585 2
    with these constructs. (<literal>\echo ${${foo}}</literal> doesn't work.) On the
    other hand, <literal>\set bar $foo</literal> is a perfectly valid way to copy
d1591 1
a1591 1
    If you call <command>\set</command> without an argument, the variable is simply
d1843 1
a1843 1
    regular <acronym>SQL</acronym> statements. The syntax for this is to prepend
d1863 1
a1863 2
testdb=> <userinput>\set content `cat my_file.txt`</userinput>
testdb=> <userinput>\set content "'${content}'"</userinput>
d1889 1
a1889 1
    is not set, the character sequence <quote>colon-name</quote> is not changed. In any
d1893 2
a1894 1
    array slices and type casts are <productname>PostgreSQL</productname> extensions.)
d1988 1
a1988 1
        <term><literal>%$</literal><replaceable class="parameter">name</replaceable><literal>$</literal></term>
d2045 1
a2045 1
    convenienent line editing and retrieval. The command history is stored in a file
d2051 10
a2060 1
    features.
d2075 1
a2075 1
$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib  ...
d2127 1
a2127 1
testdb=> <userinput>\set prompt1 '%n@@%m %~%R%# '</userinput>
a2242 8
      <listitem>
      <para>
      The number of options for a backslash command is limited, probably to 16.
      You can easily change this in the source code, and perhaps I will get around
      to fixing this one day. Not that there is any command
      that actually uses that many options though.
      </para>
      </listitem>
@


1.21
log
@another set of cleanups
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.20 2000/01/14 22:18:01 petere Exp $
d1947 1
a1947 1
	<listitem><para>If the username is <literal>postgres</literal>, a
d2023 3
a2025 4
    to read and execute the files <filename>/etc/psqlrc</filename> and
    <filename>$HOME/.psqlrc</filename>. They could be used to set up the client or
    the server to taste (using the <command>\set</command> and <command>SET</command>
    commands).
d2036 1
a2036 1
    named <filename>.psqlrc</filename> in your home directory and is reloaded when
d2090 1
a2090 1
testdb-> <userinput> first int4 not null default 0,</userinput>
d2098 5
a2102 5
           Table "my_table"
 Attribute | Type |        Info
-----------+------+--------------------
 first     | int4 | not null default 0
 second    | text |
@


1.20
log
@Fixed psql variables vs array syntax, as well as minor psql enhancements
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.19 2000/01/12 19:36:34 petere Exp $
d855 10
d1913 2
a1914 1
	<listitem><para>The hostname of the database server (or <quote>.</quote> if Unix domain socket).</para></listitem>
d1919 2
a1920 1
	<listitem><para>The hostname of the database server truncated after the first dot.</para></listitem>
d1930 2
a1931 1
	<listitem><para>The username you are connected as (not your local system user name).</para></listitem>
d1941 2
a1942 2
	<listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote> (tilde) if the database
	is your default database.</para></listitem>
d1947 2
a1948 1
	<listitem><para>If the username is <literal>postgres</literal>, a <quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
d1954 8
a1961 8
	In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if in single-line mode, and
	<quote>!</quote> if the session is disconnected from the database (which can only
	happen if <command>\connect</command> fails).
	In prompt 2 the sequence is replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
	or a double quote, depending on whether <application>psql</application> expects more input
	because the query wasn't terminated yet, because you are inside a <literal>/* ... */</literal>
	comment, or because you are inside a quote.
	In prompt 3 the sequence doesn't resolve to anything.</para>
d1968 6
a1973 5
	If <replaceable class="parameter">digits</replaceable> starts with <literal>0x</literal>
	the rest of the characters are interpreted at a hexadecimal digit and the
	character with the corresponding code is subsituted. If the first digit is <literal>0</literal>
	the characters are interpreted as on octal number and the corresponding character
	is substituted. Otherwise a decimal number is assumed.</para>
@


1.19
log
@Fixed a few "fixes" and bugs. Adjusted messages and options to GNU suggestions.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.18 1999/11/26 04:24:16 momjian Exp $
d35 2
a36 1
    <title>Input</title>
d38 7
a44 3
    <application>psql</application> accepts many command-line arguments,
    a rich set of meta-commands, and the full <acronym>SQL</acronym> language
    supported by <productname>PostgreSQL</productname>.
d46 1
a48 13
  <refsect2 id="R2-APP-PSQL-2">
    <refsect2info>
      <date>1998-10-26</date>
     </refsect2info>
   
    <title>Output</title>
    <para>
    <application>psql</application> returns 0 to the shell on successful
    completion of all queries, 1 for fatal errors, 2 for abrupt disconnection
    from the backend, and 3 if a non-interactive script stopped because an <acronym>SQL</acronym>
    command or psql meta-command resulted in an error.
    </para>
  </refsect2>
d58 1
a58 34
  <para>
  <application>psql</application> is a character-based front-end to 
  <productname>PostgreSQL</productname>. It enables you to type in queries
  interactively, issue them to <productname>PostgreSQL</productname>, and see
  the query results. In addition, it provides a number of meta-commands and
  various shell-like features to facilitate writing scripts and automating a wide
  variety of tasks.
  </para>

  <para>
  <application>psql</application> is a regular
  <productname>PostgreSQL</productname> client application. Hence, a
  <application>postmaster</application> process must be running on the database
  server host before <application>psql</application> is executed.  In addition,
  the correct parameters to identify the database server, such as the
  <application>postmaster</application> host name, may need to be specified as
  described below.
  </para>

  <para>
  When <application>psql</application> starts, it reads <acronym>SQL</acronym> and psql commands
  from <filename>/etc/psqlrc</filename> and then from
  <filename>$<envar>HOME</envar>/.psqlrc</filename>
  This allows commands like <command>\set</command> or the <acronym>SQL</acronym> command
  <xref linkend="SQL-SET" endterm="SQL-SET-title">, which can be used to set a variety of options,
  to be run at the start of every session.
  </para>

  <para>
  <application>psql</application> can be used in a pipe sequence, and
  automatically detects when it is not used interactively.
  </para>

  <refsect2 id="R2-APP-PSQL-3">
d60 1
a60 1
      <date>1998-09-26</date>
d66 15
a80 6
    <application>psql</application> attempts to make a connection to the
    database name at the hostname and port number, and with the user name
    specified on the command line. If any of these are omitted, the
    <application>libpq</application> client library, upon which
    <application>psql</application> is built, will choose defaults.
    (This will usually mean the environment variables <envar>PGDATABASE</envar>,
d82 1
a82 4
    respectively, if they are set. Otherwise the default host is the local host
    via Unix domain sockets, the default port is decided at compile time,
    the default user is the system user name, and the default database is
    the one with the same name as the user.)
d120 3
a122 2
    semicolon is reached. If the database server reports success, the query
    results are displayed on the screen.
d143 5
a147 6
    unquoted backslash is a <application>psql</application> meta-command.
    Anything else is <acronym>SQL</acronym> and simply goes into the current
    query buffer (and once you have at least one complete query, it gets
    automatically submitted to the backend). For this reason,
    <application>psql</application> meta-commands are more commonly called
    slash or backslash commands.
d237 2
a238 5
	If <replaceable class="parameter">username</replaceable> is omitted or
	<literal>-</literal> the current user name is assumed. If
	<replaceable class="parameter">username</replaceable> is <literal>?</literal>
	<application>psql</application> will prompt for the new user name
	interactively.
d259 1
a259 1
        <term><literal>\copy</literal> [ <literal>binary</literal> ] <replaceable class="parameter">table</replaceable>
d261 3
a263 2
	<replaceable class="parameter">filename</replaceable> [ <literal>with delimiters</literal>
	'<replaceable class="parameter">character</replaceable>' ]
d293 12
d645 1
a645 1
	See the description of the <envar>lo_transaction</envar> variable for
d668 1
a668 1
	<command>\lo_list?</command> command.
d679 1
a679 1
	See the description of the <envar>lo_transaction</envar> variable for
d712 1
a712 1
	See the description of the <envar>lo_transaction</envar> variable for
d734 2
a735 1
	<quote>Query results</quote> includes all tables and notices obtained
d737 2
a738 1
	commands that query the database (such as <command>\d</command>).
d903 1
a903 1
	  Otherwise <filename>/bin/more</filename> is assumed.
d1005 2
a1006 4
	is given, the variable is unset (which is different from setting it to,
	for example, an empty string: <literal>\set foo ''</literal>). If no
	arguments are given, all currently defined variables are listed with their
	values.
d1171 1
a1171 8
  are not available on all systems, so you are advised to consider carefully
  whether to use them.
  </para>

  <para>
  Many command line options are equivalent to an internal slash command or to
  setting some variable. Those will not be explained in detail here. Instead,
  you are asked to look them up in the respective section.
d1193 1
a1193 2
      and then exit.  This is useful for shell scripts, typically in
      conjunction with the <option>-q</option> option.
d1225 1
a1225 1
      This is equivalent to setting the variable <envar>echo</envar>.
d1232 1
a1232 1
      <term>-E, --echo-all</term>
d1238 1
a1238 1
      <envar>echo_secret</envar> from within <application>psql</application>.
d1308 1
a1308 1
      Do not use the readline library for input line editing and command history.
d1360 1
a1360 1
      also set the <envar>quiet</envar> variable to achieve the same effect.
d1382 1
a1382 1
      Runs in single-line mode where a newline sends a query, in addition to a semicolon.
d1390 1
a1390 2
      the unexperienced user. Moral: Unless you exclusively type short queries,
      avoid using this mode.
d1442 1
a1442 3
      instead of the default. (You must have permission to do so, of course.) If
      <replaceable class="parameter">username</replaceable> is <quote>?</quote>, <application>psql</application>
      issues an interactive prompt for the user name.
d1454 3
a1456 1
      line.
d1473 1
a1473 1
      <term>-W</term>
d1488 1
a1488 2
      the content of the environment variable <envar>PGPASSWORD</envar> is
      taken. If this is not set, the connection attempt will fail.
d1490 3
d1494 3
a1496 1
      <caution>
d1498 2
a1499 2
      If you are considering setting the variable <envar>PGPASSWORD</envar> to do
      authentication, you have a problem.
a1500 1
      </caution>
d1506 1
a1506 1
      <term>-x</term>
d1509 1
a1509 2
      Turns on extended row format mode. This is equivalent to the command
      <command>\x</command>.
a1516 6
  <para>
  You may set environment variables to avoid typing some of the above
  options.  See the section <quote>Connection To A Database</quote> above
  and in particular the documentation of the <application>libpq</application>
  client library.
  </para>
d1551 1
a1551 1
    (The curly braces are required. This is not <productname>Perl</productname>.) No variable substitution
d1571 3
a1573 27
    <application>psql</application>'s internal variable names can consist of
    letters, numbers, and underscores in any order and any number of them.
    It is recommended, however, that you stick to lower-case letters and do not
    begin with a digit. The partial rationale for this follows.
    </para>

    <para>
    If you attempt to refer to a variable that is not set,
    <application>psql</application> first checks if it is the name of one of
    several defined <quote>magic</quote> variables. Those variables are
    maintained internally and always have a value (at least when their semantics
    permit it). By convention they all start with an upper-case letter. You can
    set those variables manually, but that will <quote>shadow</quote> their
    special meaning, until you unset your personal copy. Finally, if no match is
    found that way, the value of the respective environment variable is
    substituted.
    </para>

    <para>
    Currently, the following <quote>magic</quote> variables are defined:
    <envar>Version</envar> which contains a string with the version of
    <application>psql</application>; <envar>Database</envar>, <envar>Host</envar>,
    <envar>Port</envar>, <envar>User</envar> are the currently active
    connection options. <envar>LastOid</envar> contains the oid that was the
    result of the last <command>INSERT</command> or <command>\lo_import</command>
    command. If the last command was not one of those two, the value
    is undefined.
d1577 2
d1581 2
a1582 1
    by altering the value of the variable. Although you can use these
d1584 5
a1588 4
    program behavior might grow really strange really quickly. Note that the
    majority variables are <quote>boolean</quote> variables, that is, they
    only care whether or not are they set, not what to. A list of all specially
    treated variables follows.
d1591 38
a1628 1
        <term><envar>die_on_error</envar></term>
d1633 2
a1634 1
	processing continues. This is often less than desirable. If this variable
d1646 1
a1646 1
        <term><envar>echo</envar></term>
d1649 48
a1696 3
	If set, all lines from a script are written to the standard output before they
	are executed. To specify this on program startup, in conjunction with the
	<option>-f</option> option perhaps, use the switch <option>-e</option>.
d1698 5
d1707 1
a1707 1
        <term><envar>echo_secret</envar></term>
d1710 4
a1713 5
	When this variable is set and a backslash command queries the database, the query
	is first shown. This way you can study the <productname>PostgreSQL</productname>
	internals and provide similar functionality in your own programs. If you set the
	variable to the value <quote>noexec</quote>, the queries are just shown but are
	not actually sent to the backend and executed.
d1719 1
a1719 1
        <term><envar>lo_transaction</envar></term>
d1735 1
a1735 1
        action not being performed anyway).
d1750 11
a1760 1
        <term><envar>prompt1</envar>, <envar>prompt2</envar>, <envar>prompt3</envar></term>
d1772 1
a1772 1
        <term><envar>quiet</envar></term>
d1782 1
a1782 1
        <term><envar>singleline</envar></term>
d1792 1
a1792 1
        <term><envar>singlestep</envar></term>
d1799 11
d1868 9
d1885 2
a1886 2
    your preference. The three variables <envar>prompt1</envar>, <envar>prompt2</envar>,
    and <envar>prompt3</envar> contain strings and special escape sequences
d1987 6
d1995 61
d2204 3
a2206 17
      There are about three different parsers in <application>psql</application>,
      in addition to the backend <acronym>SQL</acronym> parser, all doing their own thing
      and attempting to get along with each other. Sometimes they do, sometimes
      they don't. An excellent example of this can be seen in section
      <quote><xref linkend="APP-PSQL-sql-interpol" endterm="APP-PSQL-sql-interpol-title"></quote>.
      There are vague dreams of using <application>flex</application> in the future,
      but it won't happen soon.
      </para>
      </listitem>

      <listitem>
      <para>
      Several string buffers are assigned fixed sizes at compile time. These
      are usually based on certain settings about what the backend can accept
      for a particular quantity. If you use <application>psql</application> with
      a different backend than the one it was configured for, you might encounter
      these limits sooner rather than later.
d2214 1
a2214 1
      to fixing this one day (see previous item). Not that there is any command
a2219 35
  </refsect2>

  <refsect2>
    <title><acronym>GNU</acronym> readline</title>

    <para>
    A great deal of <application>psql</application>'s convenience is owed to it
    using the <acronym>GNU</acronym> readline and history library for accepting
    and storing user input. To verify whether your copy of <application>psql</application>
    was compiled with readline support, execute <literal>psql -V</literal> and check the
    output for the words <quote>readline</quote> and <quote>history</quote>.
    </para>

    <para>
    If you have the readline library installed but <application>psql</application>
    does not seem to use it, you must make sure that <productname>PostgreSQL</productname>'s
    top-level <filename>configure</filename> script finds it. <filename>configure</filename>
    needs to find both the library <filename>libreadline.a</filename>
    (or <filename>libreadline.so</filename> on systems with shared libraries)
    <emphasis>and</emphasis> the header files <filename>readline.h</filename> and
    <filename>history.h</filename> (or <filename>readline/readline.h</filename> and
    <filename>readline/history.h</filename>) in appropriate directories. If
    you have the library and header files installed in an obscure place you
    must tell <filename>configure</filename> about them, for example:
<programlisting>
$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib  ...
</programlisting>
    Then you have to recompile <application>psql</application> (not necessarily
    the entire code tree).
    </para>

    <para>
    The <acronym>GNU</acronym> readline library can be obtained from the <acronym>GNU</acronym>
    project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
    </para>
@


1.18
log
@* Includes tab completion. It's not magic, but it's very cool. At any
rate
  it's better than what used to be there.

* Does proper SQL "host variable" substitution as pointed out by Andreas
  Zeugwetter (thanks): select * from :foo; Also some changes in how ':'
  and ';' are treated (escape with \ to send to backend). This does
_not_
  affect the '::' cast operator, but perhaps others that contain : or ;
  (but there are none right now).

* To show description with a <something> listing, append '?' to command
  name, e.g., \df?. This seemed to be the convenient and logical
solution.
  Or append a '+' to see more useless information, e.g., \df+.

* Fixed fflush()'ing bug pointed out by Jan during the regression test
  discussion.

* Added LastOid variable. This ought to take care of TODO item "Add a
  function to return the last inserted oid, for use in psql scripts"
  (under CLIENTS)
  E.g.,
insert into foo values(...);
insert into bar values(..., :LastOid);
\echo $LastOid

* \d command shows constraints, rules, and triggers defined on the table
  (in addition to indices)

* Various fixes, optimizations, corrections

* Documentation update as well


Note: This now requires snprintf(), which, if necessary, is taken from
src/backend/port. This is certainly a little weird, but it should
suffice
until a source tree cleanup is done.

Enjoy.

--
Peter Eisentraut                  Sernanders väg 10:115
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.17 1999/11/05 18:21:08 momjian Exp $
d355 1
a355 1
	The command form <literal>\d?</literal> is identical, but any comments
a377 4
        If the alternative command form <literal>\da?</literal> is used,
        comments are listed for each function as well. The command form
        <literal>\da+</literal> will show more information about each aggregate
        function, which is usually not of general interest.
d425 1
a425 2
        each function is shown. Comments for each function can be shown with
        the <literal>\df?</literal> form.
d445 1
a445 1
	whose name matches. If one appends a <quote>?</quote> to the command name,
a473 4
        <para>
        If the form <literal>\do?</literal> is used, comments are listed for
        each operator.
        </para>
d494 1
a494 2
        The command forms <literal>\dT+</literal> and <literal>\dT?</literal> show extra information
        and the associated descriptions of the types, respectively.
d641 1
a641 1
        <quote>?</quote> (question mark) to the command name to see any descriptions
a715 2
	Append a question mark to the command name (<literal>\lo_list?</literal>) to
        see the the associated comments as well.
d1194 3
a1196 5
  Unix short options, and <acronym>GNU</acronym>-style long options. Since the
  latter are not available on all systems, you are advised to consider carefully
  whether to use them, if you are writing scripts, etc. For support on the
  <productname>PostgreSQL</productname> mailing lists, you are asked to only
  use the standard short options.
d1290 1
a1290 1
      <term>-F, --field-sep <replaceable class="parameter">separator</replaceable></term>
d1347 1
a1347 1
      <term>-o, --out <replaceable class="parameter">filename</replaceable></term>
d1389 1
a1389 2
      By default, it prints welcome messages, various informational output and
      prompts for each query.
d1499 1
a1499 29
      Shows version information about <application>psql</application> and your
      <productname>PostgreSQL</productname> database server, if it could be reached.
      </para>

      <para>
      The output looks similar to this:
<programlisting>
~$ <userinput>psql -V</userinput>
Server: PostgreSQL 6.5.2 on i586-pc-linux-gnu, compiled by egcs
psql 6.6.0 on i586-pc-linux-gnu, compiled by gcc 2.8.1 (Oct 27 1999 15:15:04), long options,
readline, history, locale, assert checks
</programlisting>
      The <quote>Server</quote> line is identical to the one returned by the
      backend function <function>version()</function> and thus might vary
      if you query different servers by using different connection
      options.
      </para>

      <para>
      The <quote>psql</quote> line is compiled into the <application>psql</application>
      binary. It shows you which <productname>PostgreSQL</productname> release
      it was distributed with and what optional features were compiled into it.
      Although in general (as in the example above) you can use <application>psql</application>
      and database servers from different versions (if they don't differ too much)
      this is not recommended or
      even necessary. The optional features indicate only <application>psql</application>'s
      capabilities but if <application>psql</application> was configured with
      the same source tree as the rest of the distribution, it gives you an
      indication about other parts of the installation as well.
a2106 20
  </refsect2>

  <refsect2>
    <title>History and Lineage</title>

    <para>
    <application>psql</application> first appeared in <productname>Postgres95</productname>
    to complement and later replace the <application>monitor</application> program. (You see this
    name here or there in really old files. The author has never had the pleasure to use this
    program though.) An uncountable number of people have added features since to reflect
    the enhancements in the actual database server.
    </para>

    <para>
    The present version is the result of a major clean-up and re-write in 1999 by
    <ulink URL="mailto:peter_e@@gmx.net">Peter Eisentraut</ulink> in preparation for release 7.0.
    Many people had again contributed their ideas. A bunch of features were stolen
    from various shells (in case you hadn't noticed), in particular
    <application>tcsh</application>.
    </para>
@


1.17
log
@Update psql banner
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.16 1999/11/05 15:44:56 momjian Exp $
d93 5
d112 1
a112 1
    <envar>PGHOST</envar>, <envar>PGPORT</envar>, <envar>PQUSER</envar>,
d137 1
a137 1
    <programlisting>
d148 1
a148 1
    </programlisting>
a163 5

    <para>
    <application>psql</application> can be used in a pipe sequence, and
    automatically detects when it is not used interactively.
    </para>
d346 1
a346 1
	Shows all column of <replaceable class="parameter">relation</replaceable>
d350 2
d355 2
a356 4
	If the relation is, in fact, a table, any defined indices are also listed.
	If the relation is a view, the view definition is also shown.
	If the variable <envar>description</envar> is set, any comments associated
	with a table columns are shown as well.
d378 4
a381 2
	If the variable <envar>description</envar> is set, comments are listed for
	each function as well.
d394 1
a394 1
        <programlisting>
d401 1
a401 1
        </programlisting>                                                                                      
d428 3
a430 2
        If the variable <envar>description</envar> is set, comments are listed for
        each function as well. 
d450 1
a450 1
	whose name matches. If the variable <envar>description</envar> is set,
d468 1
a468 1
        <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
d472 1
a472 1
        If <replaceable class="parameter">name</replaceable>
d474 4
a477 3
        (Note that, unlike with similar commands, this is not a regular expression
        because operator names were likely to interfere with regular expression
        meta-characters.)
d480 1
a480 1
        If the variable <envar>description</envar> is set, comments are listed for
d502 3
a504 3
        List all data types or only those that match <replaceable class="parameter">pattern</replaceable>.
        If the variable <envar>description</envar> is set, each type is listed with
	its associated description.
d526 2
a527 2
        use <command>\i</command> for that.) In particular, this means that
        if the query ends (or rather contains) a semicolon, it is immediately
d549 1
a549 1
        <programlisting>
d552 1
a552 1
        </programlisting>
d586 1
a586 1
        <replaceable class="parameter">command</replaceable>. A blank <literal>\g</literal>
d598 1
a598 2
        If <replaceable class="parameter">command</replaceable> is not a defined <acronym>SQL</acronym> command
        or if <replaceable class="parameter">command</replaceable> is not specified,
d634 1
a634 1
	and executes it as though it has been typed on the keyboard.
d650 3
a652 3
        List all the databases in the server as well as their owners. If the
	variable <envar>description</envar> is set, any descriptions for
	the databases are shown as well. If your <productname>PostgreSQL</productname>
d694 1
a694 1
	<programlisting>
d697 1
a697 1
        </programlisting>
d699 1
a699 1
	which one ought to remember if one wants to access the object every again.
d702 1
a702 1
	<command>\lo_list</command> command.
d726 2
a727 2
	If the variable <envar>description</envar> is set, the associated
	comments are shown as well.
d869 1
a869 1
	  for, say, an empty string. There one might choose to write
d1021 1
a1021 1
	As of <application>psql</application> version 6.6 it is no longer
d1040 1
a1040 1
	for example, and empty string: <literal>\set foo ''</literal>). If no
d1046 2
a1047 5
	Valid variable names can contain lower-case characters, digits, and
	underscores. In particular, no upper-case characters are allowed, as
	those are reserved for certain <quote>magic</quote> variables and
	environment variables. See the section about <application>psql</application>
	variables for details.
d1122 1
a1122 1
	<programlisting>
d1129 1
a1129 1
        </programlisting>
d1173 4
a1176 1
        <replaceable class="parameter">command</replaceable>.
d1296 1
a1296 1
      After the file is processed, <application>terminates</application>.
d1520 1
a1520 1
      <programlisting>
d1525 1
a1525 1
      </programlisting>
d1559 1
a1559 1
      As of version 6.6, <application>psql</application> automatically issues a
d1612 1
a1612 1
    similar to common Unix command shells. Variables are simply name/values
d1615 1
a1615 1
    <programlisting>
d1617 1
a1617 1
    </programlisting>
d1621 1
a1621 1
    <programlisting>
d1624 1
a1624 1
    </programlisting>
d1627 1
a1627 1
    <programlisting>
d1630 1
a1630 1
    </programlisting>
d1633 1
a1633 1
    that have special parsing rules (<command>\copy</command>, <command>\help</command>).
d1640 4
a1643 3
    such as <literal>\set "${foo}bar" 'something'</literal> and get <quote>variable
    variables</quote> of <productname>Perl</productname> or <productname><acronym>PHP</acronym></productname>
    fame. Unfortunately (or fortunately?), there is not way to do anything useful
d1652 15
a1666 8
    lower-case letters, numbers, and underscores in any order and any number of
    them. Upper-case letters are not allowed. (There is a reason for that. Keep reading.)
    If you attempt to refer to a variable that does not consist of those
    characters <application>psql</application> first checks if it is the name of
    one of several defined <quote>magic</quote> variables. Those variables you cannot
    set but they always have a value. By convention they all start with an
    upper-case letter. Finally, if no match is found that way, the value of
    the respective environment variable is substituted.
d1674 4
a1677 1
    connection options.
a1690 13
        <term><envar>description</envar></term>
	<listitem>
	<para>
	If set, the various <command>\d*</command> commands as well as
	<command>\l</command> and <command>\lo_list</command> show object
	descriptions along with the normal information. (Except for
	<command>\dd</command> which always shows descriptions as this
	is its very purpose.)
	</para>
	</listitem>
      </varlistentry>

      <varlistentry>
d1735 14
a1748 11
	If you use the <productname>PostgreSQL</productname> large object interface to store
	data that does not fit into one tuple specially all the operations must be contained
	in a transaction block. (See the documentation of the large object interface for
	more information.) Since <application>psql</application> has no way to keep track if
	you already have a transaction in progress when you call one of its internal commands
	<command>\lo_export</command>, <command>\lo_import</command>, <command>\lo_unlink</command>
	it must take some arbitrary action. This action could either be to roll back any transaction
	that might already be in progress, or to commit any such transaction, or to do nothing
	at all. In the latter case you must provide you own <command>BEGIN</command>/<command>END</command>
	block or the results are unpredictable (usually resulting in the desired action not being
	performed anyway).
d1753 5
a1757 4
	<quote>rollback</quote>, <quote>commit</quote>, or <quote>nothing</quote>. The default is
	to roll back the transaction. If you just want to load one or a few objects this is fine.
	However, if you intend to transfer many large objects, it might be advisable to
	provide one explicit transaction block around all commands.
a1801 10

      <varlistentry>
        <term><envar>sql_interpol</envar></term>
	<listitem>
	<para>
	The escape character for <acronym>SQL</acronym> variable interpolation. See below.
	</para>
	</listitem>
      </varlistentry>

d1815 3
a1817 20
    regular <acronym>SQL</acronym> statements. In order not to break existing
    <acronym>SQL</acronym> statements, you must choose your own special
    character that tells <application>psql</application> that you wish to
    interpolate the value of a variable here. You do this by setting the
    variable <envar>sql_interpol</envar>. Only the first character will be
    looked at. You can set this variable to anything you want but, for instance,
    letters, numbers, semicolons, or backslashes will not make your life easier.
    Reasonable choices include the dollar (<quote>$</quote>) and pound
    (<quote>#</quote>) signs.
    <programlisting>
testdb=> <userinput>\set sql_interpol '#'</userinput>
    </programlisting>
    </para>

    <para>
    Once this is set up, whenever <application>psql</application> sees the
    magic character where it would expect a query, it will continue scanning
    until it sees the same character again and will interpret anything in
    between as a variable name.
    <programlisting>
d1819 2
a1820 2
testdb=> <userinput>SELECT * FROM #foo#;</userinput>
    </programlisting>
d1824 2
d1829 4
a1832 1
    One possible application of this mechanism is to copy the contents of a file
d1834 1
a1834 1
    <programlisting>
d1836 3
a1838 2
testdb=> <userinput>INSERT INTO my_table VALUES ('#content#');</userinput>
    </programlisting>
d1841 1
a1841 1
    they don't cause a syntax error when the second line is processed. This
d1843 1
a1843 1
    <programlisting>
d1845 1
a1845 1
    </programlisting>
d1990 1
a1990 1
  <programlisting>
d1996 1
a1996 1
  </programlisting>
d1998 1
a1998 1
  <programlisting>
d2006 1
a2006 1
  </programlisting>
d2009 1
a2009 1
  <programlisting>
d2012 1
a2012 1
  </programlisting>
d2014 1
a2014 1
  <programlisting>
d2024 1
a2024 1
  </programlisting>
d2028 1
a2028 1
  <programlisting>
d2066 1
a2066 1
  </programlisting>
d2068 1
a2068 1
  <programlisting>
d2086 1
a2086 1
  </programlisting>
d2110 1
a2110 1
      <programlisting>
d2113 1
a2113 1
      </programlisting>
d2125 2
a2126 1
      Changing this situation, however, is beyond feasability.
d2139 9
d2166 3
a2168 3
    Many people had again contributed their ideas. The author would also like
    to recognize the influence of <application>tcsh</application> at a number
    of places.
d2194 1
a2194 1
    <programlisting>
d2196 1
a2196 1
    </programlisting>
@


1.16
log
@Update psql display.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.15 1999/11/05 00:57:39 momjian Exp $
d136 5
a140 5
Type \copyright for distribution terms
     \h for help with SQL commands
     \? for help on internal slash commands
     \g or terminate with semicolon to execute query
     \q to quit
@


1.15
log
@Update man pages for new banner.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.14 1999/11/04 22:07:56 momjian Exp $
d135 1
@


1.14
log
@Update psql with man pages and new version of help.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.11 1999/07/30 00:59:50 momjian Exp $
d135 6
a140 6
(Please type \copyright to see the distribution terms of PostgreSQL.)
 
Type \h for help with SQL commands,
     \? for help on internal slash commands,
     \q to quit,
     \g or terminate with semicolon to execute query.
@


1.13
log
@improve manual page
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.12 1999/10/14 01:28:41 momjian Exp $
d7 22
a28 26
 <refmeta>
  <refentrytitle id="app-psql-title">
   <application>psql</application>
  </refentrytitle>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>psql</application>
  </refname>
  <refpurpose>
   <productname>Postgres</productname> interactive client
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
psql [ <replaceable class="parameter">dbname</replaceable> ]
psql -A [ -c <replaceable class="parameter">query</replaceable> ] [ -d <replaceable class="parameter">dbname</replaceable> ]
    -e -E [ -f <replaceable class="parameter">filename</replaceable> ] [ -F <replaceable class="parameter">separator</replaceable> ]
    [ -h <replaceable class="parameter">hostname</replaceable> ] -Hln [ -o <replaceable class="parameter">filename</replaceable> ]
    [ -p <replaceable class="parameter">port</replaceable> ] -qsSt [ -T <replaceable class="parameter">table_o</replaceable> ] -ux
    [ <replaceable class="parameter">dbname</replaceable> ]
  </synopsis>
d31 6
a36 7
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
d39 2
a40 112
    supported by <productname>Postgres</productname>. The most common
    command-line arguments are:

    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">dbname</replaceable></term>
      <listitem>
       <para>
	The name of an existing database to access.
	<replaceable class="parameter">dbname</replaceable>
	defaults to the value of the
	<envar>USER</envar>
	environment variable or, if that's not set, to the Unix account name of the
	current user.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-c <replaceable class="parameter">query</replaceable></term>
      <listitem>
       <para>
	A single query to run. <application>psql</application> will exit on completion.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    The full set of command-line arguments and meta-commands are described in a subsequent
    section.
   </para>

   <para>
    There are some environment variables which can be used in liu of
    command line arguments. 
    Additionally, the <productname>Postgres</productname> frontend library used by 
    the <application>psql</application> application
    looks for other optional environment variables to configure, for example,
    the style of date/time representation and the local time zone. Refer
    to the chapter on <filename>libpq</filename> in the
    <citetitle>Programmer's Guide</citetitle> for more details.
   </para>
   <para>
    You may set any of the following environment variables to avoid
    specifying command-line options:
	
    <variablelist>
     <varlistentry>
      <term><envar>PGHOST</envar></term>
      <listitem>
       <para>
	The <acronym>DNS</acronym> host name of the database server.
	Setting <envar>PGHOST</envar> to a non-zero-length string causes
	<acronym>TCP/IP</acronym> communication
	to be used, rather than the default local Unix domain sockets.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><envar>PGPORT</envar></term>
      <listitem>
       <para>
	The port number on which a <productname>Postgres</productname> server is listening.
	Defaults to <literal>5432</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><envar>PGTTY</envar></term>
      <listitem>
       <para>
	The target for display of messages from the client support library.
	Not required.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><envar>PGOPTION</envar></term>
      <listitem>
       <para>
	If <envar>PGOPTION</envar>
	is specified, then the options it contains are parsed
	<emphasis>before</emphasis>
	any command-line options.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><envar>PGREALM</envar></term>
      <listitem>
       <para>
	<envar>PGREALM</envar>
	only applies if
	<productname>Kerberos</productname>
	authentication is in use.  
	If this environment variable is set, <productname>Postgres</productname>
	will attempt authentication with servers for this realm and will use
	separate ticket files to avoid conflicts with local ticket files.
	See the <citetitle>PostgreSQL Administrator's Guide</citetitle>
	for additional information on
	<productname>Kerberos</productname>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
d44 11
a54 17
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>psql</application>
    returns 0 to the shell on successful completion of all queries,
    1 for errors, 2 for abrupt disconnection from the backend.
    <application>psql</application>
    will also return 1 if the connection to a database could not be made for
    any reason.
   </para>
   <para>
    The default TAB delimiter is used.
   </para>
d56 1
a56 1
 </refsynopsisdiv>
d58 1
a58 1
 <refsect1 id="R1-APP-PSQL-1">
d60 1
a60 1
   <date>1998-09-26</date>
d62 3
a64 3
  <title>
   Description
  </title>
d66 6
a71 6
   <application>psql</application> is a character-based front-end to 
   <productname>Postgres</productname>.
   It enables you to
   type in queries interactively, issue them to <productname>Postgres</productname>, 
   and see the query
   results.
d73 1
d75 7
a81 10
   <application>psql</application>
   is a <productname>Postgres</productname> client application.  Hence, a
   <application>postmaster</application> process
   must be running on the database server host before
   <application>psql</application>
   is executed.  In addition, the correct parameters to identify
   the database server, such as the
   <application>postmaster</application> host name,
   may need to be specified
   as described below.
d83 1
d85 6
a90 10
   When
   <application>psql</application>
   starts, it reads SQL commands from
   <filename>/etc/psqlrc</filename>
   and then from
   <filename>$(<envar>HOME</envar>)/.psqlrc</filename>
   This allows SQL commands like
   <command>SET</command>
   which can be used to set the date style to be run at the start of
   every session.
d94 25
a118 19
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Connecting To A Database
   </title>
   <para>
    <application>psql</application>
    attempts to make a connection to the database at the hostname and
    port number specified on the command line.   If the connection could not
    be made for any reason (e.g. insufficient privileges, postmaster is not
    running on the server, etc)
    .IR <application>psql</application>
    will return an error that says
    <programlisting>
     Connection to database failed.
    </programlisting>
    The reason for the connection failure is not provided.
   </para>
d122 10
a131 12
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Entering Queries
   </title>
   <para>
    In normal operation, 
    <application>psql</application> provides a prompt with the name of the
    database that <application>psql</application> is current connected to 
    followed by the string "=>".
    For example,
d134 7
a140 9
Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL
[PostgreSQL 6.5.0 on i686-pc-linux-gnu, compiled by gcc 2.7.2.3]

   type \? for help on slash commands
   type \q to quit
   type \g or terminate with semicolon to execute query
 You are currently connected to the database: testdb
	  
d143 3
a145 2
   </para>
   <para>
d147 16
a162 14
    Unless the -S option
    is set, input lines are sent to the backend when a query-terminating
    semicolon is reached.
   </para>
   <para>
    Whenever a query is executed, 
    <application>psql</application> also polls for asynchronous notification
    events generated by <command>LISTEN</command> and <command>NOTIFY</command>.
   </para>
   <para>
    <application>psql</application>
    can be used in a pipe sequence, and automatically detects when it
    is not listening or talking to a real tty.
   </para>
d164 25
d190 11
a200 2
  <refsect2 id="R2-APP-PSQL-5">
   <title>Paging To Screen</title>
a201 2
   <note>
    <title>Author</title>
d203 5
a207 1
     From Brett McCormick on the mailing list 1998-04-04.
a208 1
   </note>
d210 7
a216 6
   <para>
    To affect the paging behavior of your <command>psql</command> output,
    set or unset your PAGER environment variable.  I always have to set mine
    before it will pause.  And of course you have to do this before
    starting the program.
   </para>
d218 10
a227 2
   <para>
    In csh/tcsh or other C shells:
d229 961
a1189 3
    <programlisting>
% unsetenv PAGER
    </programlisting>
a1190 1
    while in sh/bash or other Bourne shells:
a1191 6
    <programlisting>
% unset PAGER
    </programlisting>
   </para>
  </refsect2>
 </refsect1>
d1193 1
a1193 1
 <refsect1 id="R1-APP-PSQL-2">
d1195 1
a1195 1
   <date>1998-09-26</date>
d1197 3
a1199 3
  <title>
   Command-line Options
  </title>
d1201 7
a1207 2
   <application>psql</application>
   understands the following command-line options:
d1209 8
a1216 1
   <variablelist>
d1218 2
a1219 2
     <term>-A</term>
     <listitem>
d1221 2
a1222 1
       Turn off fill justification when printing out table elements.
d1224 1
a1224 1
     </listitem>
d1226 1
d1229 2
a1230 2
     <term>-c <replaceable class="parameter">query</replaceable></term>
     <listitem>
d1232 4
a1235 6
       Specifies that
       <application>psql</application>
       is to execute one query string,
       <replaceable class="parameter">query</replaceable>,
       and then exit.  This is useful for shell scripts, typically in
       conjunction with the <option>-q</option> option in shell scripts.
a1236 6
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-d <replaceable class="parameter">dbname</replaceable></term>
     <listitem>
d1238 7
a1244 3
       Specifies the name of the database to connect to. This is equivalent to specifying
       <replaceable class="parameter">dbname</replaceable> as the last field in the
       command line.
d1246 1
a1246 1
     </listitem>
d1249 1
d1251 2
a1252 2
     <term>-e</term>
     <listitem>
d1254 3
a1256 1
       Echo the query sent to the backend
d1258 1
a1258 1
     </listitem>
d1261 1
d1263 2
a1264 2
     <term>-E</term>
     <listitem>
d1266 2
a1267 1
       Echo the actual query generated by \d and other backslash commands
d1269 1
a1269 1
     </listitem>
d1272 1
d1274 2
a1275 2
     <term>-f <replaceable class="parameter">filename</replaceable></term>
     <listitem>
d1277 4
a1280 3
       Use the file <replaceable class="parameter">filename</replaceable>
       as the source of queries instead of reading queries interactively.
       This file must be specified for and visible to the client frontend.
d1282 1
a1282 1
     </listitem>
d1285 1
d1287 2
a1288 2
     <term>-F <replaceable class="parameter">separator</replaceable></term>
     <listitem>
d1290 4
a1293 3
       Use <replaceable class="parameter">separator</replaceable>
       as the field separator.
       The default is an ASCII vertical bar ("|").
d1295 1
a1295 1
     </listitem>
d1298 1
d1300 2
a1301 2
     <term>-h <replaceable class="parameter">hostname</replaceable></term>
     <listitem>
d1303 2
a1304 5
       Specifies the host name of the machine on which the
       <application>postmaster</application>
       is running.
       Without this option, communication is performed using
       local Unix domain sockets.
d1306 1
a1306 1
     </listitem>
d1309 1
d1311 2
a1312 2
     <term>-H</term>
     <listitem>
d1314 4
a1317 3
       Turns on
       <acronym>HTML 3.0</acronym>
       tabular output.
d1319 1
a1319 1
     </listitem>
d1322 1
d1324 2
a1325 2
     <term>-l</term>
     <listitem>
d1327 3
a1329 1
       Lists all available databases, then exit. Other non-connection options are ignored.
d1331 1
a1331 1
     </listitem>
d1334 1
d1336 2
a1337 2
     <term>-n</term>
     <listitem>
d1339 2
a1340 1
       Do not use the readline library for input line editing and command history.
d1342 1
a1342 1
     </listitem>
d1345 1
d1347 2
a1348 2
     <term>-o <replaceable class="parameter">filename</replaceable></term>
     <listitem>
d1350 1
a1350 2
       Put all output into file <replaceable class="parameter">filename</replaceable>.
       The path must be writable by the client.
d1352 1
a1352 1
     </listitem>
d1355 1
d1357 2
a1358 2
     <term>-p <replaceable class="parameter">port</replaceable></term>
     <listitem>
d1360 2
a1361 6
       Specifies the TCP/IP port or, by omission, the local Unix domain socket file
       extension on which the
       <application>postmaster</application>
       is listening for connections.  Defaults to the value of the
       <envar>PGPORT</envar>
       environment variable, if set, or to 5432.
d1363 1
a1363 1
     </listitem>
d1366 1
d1368 2
a1369 2
     <term>-q</term>
     <listitem>
d1371 5
a1375 6
       Specifies that
       <application>psql</application>
       should do its work quietly.  By default, it
       prints welcome and exit messages and prompts for each query.
       If this option is used, none of this happens. This is useful with the
       <option>-c</option> option.
d1377 1
a1377 1
     </listitem>
d1380 1
d1382 2
a1383 2
     <term>-s</term>
     <listitem>
d1385 4
a1388 2
       Run in single-step mode where the user is prompted for each query before
       it is sent to the backend.
d1390 1
a1390 1
     </listitem>
d1393 1
d1395 2
a1396 2
     <term>-S</term>
     <listitem>
d1398 6
a1403 2
       Runs in single-line mode where each query is terminated by a newline,
       instead of a semicolon.
d1405 1
a1405 1
     </listitem>
d1408 1
d1410 2
a1411 2
     <term>-t</term>
     <listitem>
d1413 3
a1415 4
       Turn off printing of column names and result row count.
       This is useful with the
       <option>-c</option>
       option in shell scripts.
d1417 1
a1417 1
     </listitem>
d1420 1
d1422 2
a1423 2
     <term>-T <replaceable class="parameter">table_options</replaceable></term>
     <listitem>
d1425 1
a1425 5
       Allows you to specify options to be placed within the
       <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym>
       tabular output.For example, <literal>border</literal>
       will give you tables with borders.
       This must be used in conjunction with the <option>-H</option> option.
a1426 2
     </listitem>
    </varlistentry>
d1428 1
a1428 3
    <varlistentry>
     <term>-u</term>
     <listitem>
d1430 5
a1434 5
       Asks the user for the user name and password before connecting to the database.
       If the database does not require password authentication then these are
       ignored.  If the option is not used (and the PGPASSWORD environment variable
       is not set) and the database requires password authentication, then the
       connection will fail.  The user name is ignored anyway.
d1436 2
a1437 1
     </listitem>
d1440 1
d1442 2
a1443 2
     <term>-x</term>
     <listitem>
d1445 2
a1446 4
       Turns on extended row format mode. When enabled each row will have its column
       names printed on the left with the column values printed on the right.
       This is useful for rows which are otherwise too long to fit into
       one screen line. HTML row output supports this mode also.
d1448 1
a1448 1
     </listitem>
a1449 7
   </variablelist>
  </para>
  <para>
   You may set environment variables to avoid typing some of the above
   options.  See the section on environment variables below.
  </para>
 </refsect1>
a1450 29
 <refsect1 id="R1-APP-PSQL-3">
  <refsect1info>
   <date>1998-09-26</date>
  </refsect1info>
  <title>
   <application>psql</application> Meta-Commands
  </title>
  <para>
   Anything you enter in <application>psql</application> 
   that begins with an unquoted backslash is a <application>psql</application>
   meta-command.  Anything else is <acronym>SQL</acronym>
   and simply goes into the current query buffer
   (and once you have at least one complete query, it gets automatically 
   submitted to the backend).  
   <application>psql</application> meta-commands are also called slash commands.
  </para>
  <para>
   The format of a <application>psql</application> command is the backslash, 
   followed immediately by
   a command verb, then any arguments.  The arguments are separated from the
   command verb and each other by any number of white space characters.
  </para>
  <para>
   With single character command verbs, you don't actually need to separate the
   command verb from the argument with white space, for historical reasons.
   You should anyway.
  </para>
  <para>
   The following meta-commands are defined:
a1451 1
   <variablelist>
d1453 2
a1454 2
     <term><literal>\a</literal></term>
     <listitem>
d1456 2
a1457 1
       Toggle field alignment when printing out table elements.
d1459 1
a1459 1
     </listitem>
d1462 1
d1464 2
a1465 2
     <term><literal>\C</literal> <replaceable class="parameter">caption</replaceable></term>
     <listitem>
d1467 2
a1468 2
       Set the HTML3.0 table caption to 
       <quote><replaceable class="parameter">caption</replaceable></quote>.
a1469 2
     </listitem>
    </varlistentry>
a1470 3
    <varlistentry>
     <term><literal>\connect</literal> <replaceable class="parameter">meter"</replaceable>ceable> [ <replaceable class="parameter">username</replaceable> ]</term>
     <listitem>
d1472 4
a1475 3
       Establish a connection to a new database, using the default 
       <replaceable class="parameter">username</replaceable> if none is specified.
       The previous connection is closed.
d1477 1
a1477 1
     </listitem>
d1480 1
d1482 2
a1483 3
     <term><literal>\copy</literal> <replaceable class="parameter">meter"</replaceable>ceable> { FROM | TO } <replaceable class="parameter">filename</replaceable>
     </term>
     <listitem>
d1485 6
a1490 17
       Perform a frontend (client) copy.  This is an operation that runs a SQL COPY command,
       but instead of the backend reading or writing the specified file, and 
       consequently requiring backend access and special user privilege, 
       <application>psql</application> reads or writes the 
       file and routes the data to or from the backend.  The default
       <literal>tab</literal>
       delimiter is used.
      </para>
      <tip>
       <para>
	This operation is not as efficient as the <acronym>SQL</acronym> 
	<command>COPY</command> command because all data must pass through the
	client/server IP or socket connection. For large amounts of data this other
	technique may be preferable.
       </para>
      </tip>
     </listitem>
d1493 1
d1495 2
a1496 2
     <term><literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ]</term>
     <listitem>
d1498 3
a1500 5
       List tables in the database, or if <replaceable
	class="parameter">table</replaceable>
       is specified, list the columns in that table.
       If table name is specified as an asterisk (<quote>*</quote>),
       list all tables and column information for each tables.
d1502 1
a1502 1
     </listitem>
d1505 1
d1507 2
a1508 2
     <term><literal>\da</literal></term>
     <listitem>
d1510 2
a1511 1
       List all available aggregates.
a1512 2
     </listitem>
    </varlistentry>
a1513 3
    <varlistentry>
     <term><literal>\dd</literal> <replaceable class="parameter">object</replaceable></term>
     <listitem>
d1515 11
a1525 2
       List the description from <literal>pg_description</literal>
       of the specified object.
a1526 9
      <tip>
       <para>
	Not all objects have a description in <literal>pg_description</literal>.
	This meta-command can be useful to get a quick description of a native
	<productname>Postgres</productname> feature.
       </para>
      </tip>
     </listitem>
    </varlistentry>
a1527 3
    <varlistentry>
     <term><literal>\df</literal></term>
     <listitem>
d1529 10
a1538 1
       List functions.
d1540 1
a1540 1
     </listitem>
d1543 1
d1545 2
a1546 2
     <term><literal>\di</literal></term>
     <listitem>
d1548 4
a1551 1
       List only indexes.
a1552 2
     </listitem>
    </varlistentry>
a1553 3
    <varlistentry>
     <term><literal>\do</literal></term>
     <listitem>
d1555 7
a1561 1
       List only operators.
a1562 2
     </listitem>
    </varlistentry>
d1564 1
a1564 3
    <varlistentry>
     <term><literal>\ds</literal></term>
     <listitem>
d1566 2
a1567 1
       List only sequences.
d1569 2
a1570 1
     </listitem>
d1573 1
d1575 2
a1576 2
     <term><literal>\dS</literal></term>
     <listitem>
d1578 2
a1579 1
       List system tables and indexes.
d1581 1
a1581 1
     </listitem>
d1584 404
a1987 8
    <varlistentry>
     <term><literal>\dt</literal></term>
     <listitem>
      <para>
       List only non-system tables.
      </para>
     </listitem>
    </varlistentry>
a1988 8
    <varlistentry>
     <term><literal>\dT</literal></term>
     <listitem>
      <para>
       List types.
      </para>
     </listitem>
    </varlistentry>
d1990 2
a1991 9
    <varlistentry><term>
      <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
     <listitem>
      <para>
       Edit the current query buffer or the contents of the file
       <replaceable class="parameter">filename</replaceable>.
      </para>
     </listitem>
    </varlistentry>
d1993 8
a2000 10
    <varlistentry>
     <term><literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
     <listitem>
      <para>
       Edit the current query buffer or the contents of the file
       <replaceable class="parameter">filename</replaceable>
       and execute it upon editor exit.
      </para>
     </listitem>
    </varlistentry>
d2002 101
a2102 8
    <varlistentry>
     <term><literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ]</term>
     <listitem>
      <para>
       Set the field separator.  Default is a single blank space.
      </para>
     </listitem>
    </varlistentry>
d2104 1
a2104 11
    <varlistentry>
     <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
     <listitem>
      <para>
       Send the current query input buffer to the backend and optionally
       save the output in <replaceable class="parameter">filename</replaceable>
       or pipe the output into a separate Unix shell to execute
       <replaceable class="parameter">command</replaceable>.
      </para>
     </listitem>
    </varlistentry>
a2105 16
    <varlistentry>
     <term><literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
     <listitem>
      <para>
       Give syntax help on the specified SQL command.  
       If <replaceable class="parameter">command</replaceable> is not a defined SQL command
       (or is not documented in <application>psql</application>), or if
       <replaceable class="parameter">command</replaceable> is not specified,
       then <application>psql</application> will 
       list all the commands for which syntax help is
       available.  If <replaceable class="parameter">command</replaceable>
       is an asterisk (<quote>*</quote>), then
       give syntax help on all SQL commands.
      </para>
     </listitem>
    </varlistentry>
d2107 4
a2110 10
    <varlistentry>
     <term><literal>\H</literal></term>
     <listitem>
      <para>
       Toggle <acronym>HTML3</acronym> output. This is equivalent to
       the <option>-H</option>
       command-line option.
      </para>
     </listitem>
    </varlistentry>
d2112 1
a2112 9
    <varlistentry>
     <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
     <listitem>
      <para>
       Read queries from the file <replaceable class="parameter">filename</replaceable>
       into the query input buffer.
      </para>
     </listitem>
    </varlistentry>
d2114 2
a2115 8
    <varlistentry>
     <term><literal>\l</literal></term>
     <listitem>
      <para>
       List all the databases in the server.
      </para>
     </listitem>
    </varlistentry>
d2117 2
a2118 3
    <varlistentry>
     <term><literal>\m</literal></term>
     <listitem>
d2120 10
a2129 5
       Toggle the old monitor-like table display, which includes border characters
       surrounding the table.
       This is standard SQL output.
       By default, <application>psql</application> includes only field separators
       between columns.
d2131 1
a2131 2
     </listitem>
    </varlistentry>
d2133 1
a2133 3
    <varlistentry>
     <term><literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
     <listitem>
d2135 6
a2140 6
       Save future query results to the file
       <replaceable class="parameter">filename</replaceable> or pipe future
       results into a separate Unix shell to execute
       <replaceable class="parameter">command</replaceable>.
       If no arguments are specified, send query results to
       <filename>stdout</filename>.
d2142 1
a2142 2
     </listitem>
    </varlistentry>
d2144 1
a2144 3
    <varlistentry>
     <term><literal>\p</literal></term>
     <listitem>
d2146 5
a2150 1
       Print the current query buffer.
d2152 2
a2153 2
     </listitem>
    </varlistentry>
d2155 1
a2155 8
    <varlistentry>
     <term><literal>\q</literal></term>
     <listitem>
      <para>
       Quit the <application>psql</application> program.
      </para>
     </listitem>
    </varlistentry>
d2157 2
a2158 8
    <varlistentry>
     <term><literal>\r</literal></term>
     <listitem>
      <para>
       Reset(clear) the query buffer.
      </para>
     </listitem>
    </varlistentry>
d2160 7
a2166 13
    <varlistentry>
     <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
     <listitem>
      <para>
       Print or save the command line history to 
       <replaceable class="parameter">filename</replaceable>.
       If <replaceable class="parameter">filename</replaceable> is omitted,
       do not save subsequent commands to a history file.
       This option is only available if <application>psql</application> is
       configured to use readline.
      </para>
     </listitem>
    </varlistentry>
d2168 8
a2175 8
    <varlistentry>
     <term><literal>\t</literal></term>
     <listitem>
      <para>
       Toggle display of output column name headings and row count footer (defaults to on).
      </para>
     </listitem>
    </varlistentry>
d2177 2
a2178 13
    <varlistentry>
     <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
     <listitem>
      <para>
       Allows you to specify options to be placed within the
       <sgmltag>table ...</sgmltag> tag
       for <acronym>HTML 3.0</acronym>
       tabular output.For example, <literal>border</literal>
       will give you tables with borders.
       This must be used in conjunction with the <command>\H</command> meta-command.
      </para>
     </listitem>
    </varlistentry>
d2180 7
a2186 11
    <varlistentry>
     <term><literal>\x</literal></term>
     <listitem>
      <para>
       Toggles extended row format mode. When enabled each row will have its column
       names printed on the left with the column values printed on the right.
       This is useful for rows which are otherwise too long to fit into
       one screen line. <acronym>HTML</acronym> row output mode supports this flag too.
      </para>
     </listitem>
    </varlistentry>
d2188 17
a2204 9
    <varlistentry>
     <term><literal>\w</literal> <replaceable class="parameter">filename</replaceable></term>
     <listitem>
      <para>
       Write the current query buffer to the file
       <replaceable class="parameter">filename</replaceable>.
      </para>
     </listitem>
    </varlistentry>
d2206 5
a2210 9
    <varlistentry>
     <term><literal>\z</literal></term>
     <listitem>
      <para>
       Produces a list of all tables in the database with their appropriate ACLs
       (grant/revoke permissions) listed.
      </para>
     </listitem>
    </varlistentry>
d2212 1
a2212 9
    <varlistentry>
     <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
     <listitem>
      <para>
       Escape to a separate Unix shell or execute the Unix command
       <replaceable class="parameter">command</replaceable>.
      </para>
     </listitem>
    </varlistentry>
a2213 11
    <varlistentry>
     <term><literal>\?</literal></term>
     <listitem>
      <para>
       Get help information about the slash (<quote>\</quote>) commands.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
@


1.12
log
@Update psql \? for \w.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.11 1999/07/30 00:59:50 momjian Exp $
d674 1
a674 2
       of the specified object, which can be a
       table, table.column, type, operator, or aggregate.
@


1.11
log
@Fix description of psql flags -t and -q.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.10 1999/07/22 15:09:14 thomas Exp $
d946 1
a946 1
       Outputs the current query buffer to the file
@


1.10
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d478 1
a478 2
       prints welcome and exit messages and prompts for each query, and prints
       out the number of rows returned from a query.
d509 1
a509 1
       Turn off printing of column names.
@


1.9
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 5
d8 1
a8 1
  <refentrytitle id="psql-ref">
d23 1
a23 1
   <date>1998-09-26</date>
@


1.8
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
@d23 3
a25 5
    -e -E [ -f <replaceable class="parameter">filename</replaceable> ]
   [ -F <replaceable class="parameter">separator</replaceable> ] [ -h <replaceable class="parameter">hostname</replaceable> ]
    -Hln [ -o <replaceable class="parameter">filename</replaceable> ] [ -p
<replaceable class="parameter">port</replaceable> ]
    -qsSt [ -T <replaceable class="parameter">table_o</replaceable> ] -ux
d44 1
a44 3
      <term>
       <replaceable class="PARAMETER">dbname</replaceable>
      </term>
d58 1
a58 3
      <term>
       -c <replaceable class="parameter">query</replaceable>
      </term>
a64 1
	  
d67 1
d72 1
d89 1
a89 3
      <term>
       <envar>PGHOST</envar>
      </term>
d101 1
a101 3
      <term>
       <envar>PGPORT</envar>
      </term>
d111 1
a111 3
      <term>
       <envar>PGTTY</envar>
      </term>
d121 1
a121 3
      <term>
       <envar>PGOPTION</envar>
      </term>
d133 1
a133 3
      <term>
       <envar>PGREALM</envar>
      </term>
a163 1
    The default TAB delimiter is used.
d168 3
d327 1
a327 3
     <term>
      -A
     </term>
d336 1
a336 3
     <term>
      -c <replaceable class="parameter">query</replaceable>
     </term>
d350 1
a350 3
     <term>
      -d <replaceable class="parameter">dbname</replaceable>
     </term>
d361 1
a361 3
     <term>
      -e
     </term>
d370 1
a370 3
     <term>
      -E
     </term>
d379 1
a379 3
     <term>
      -f <replaceable class="parameter">filename</replaceable>
     </term>
d390 1
a390 3
     <term>
      -F <replaceable class="parameter">separator</replaceable>
     </term>
d401 1
a401 3
     <term>
      -h <replaceable class="parameter">hostname</replaceable>
     </term>
d414 1
a414 3
     <term>
      -H
     </term>
d425 1
a425 3
     <term>
      -l
     </term>
d434 1
a434 3
     <term>
      -n
     </term>
d443 1
a443 3
     <term>
      -o <replaceable class="parameter">filename</replaceable>
     </term>
d453 1
a453 3
     <term>
      -p <replaceable class="parameter">port</replaceable>
     </term>
d467 1
a467 3
     <term>
      -q
     </term>
d482 1
a482 3
     <term>
      -s
     </term>
d492 1
a492 3
     <term>
      -S
     </term>
d502 1
a502 3
     <term>
      -t
     </term>
d514 1
a514 3
     <term>
      -T <replaceable class="parameter">table_options</replaceable>
     </term>
d527 1
a527 3
     <term>
      -u
     </term>
d540 1
a540 3
     <term>
      -x
     </term>
d590 1
a590 3
     <term>
      <literal>\a</literal>
     </term>
d599 1
a599 3
     <term>
      <literal>\C</literal> <replaceable class="parameter">caption</replaceable>
     </term>
d609 1
a609 4
     <term>
      <literal>\connect</literal> <replaceable class="parameter">meter"</replaceable>ceable> [ <replaceable
       class="parameter">username</replaceable> ]
     </term>
d620 1
a620 3
     <term>
      <literal>\copy</literal> <replaceable class="parameter">meter"</replaceable>ceable> { FROM | TO }
      <replaceable class="parameter">filename</replaceable>
d644 1
a644 3
     <term>
      <literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ]
     </term>
d657 1
a657 3
     <term>
      <literal>\da</literal>
     </term>
d666 1
a666 3
     <term>
      <literal>\dd</literal> <replaceable class="parameter">object</replaceable>
     </term>
d684 1
a684 3
     <term>
      <literal>\df</literal>
     </term>
d693 1
a693 3
     <term>
      <literal>\di</literal>
     </term>
d702 1
a702 3
     <term>
      <literal>\do</literal>
     </term>
d711 1
a711 3
     <term>
      <literal>\ds</literal>
     </term>
d720 1
a720 3
     <term>
      <literal>\dS</literal>
     </term>
d729 1
a729 3
     <term>
      <literal>\dt</literal>
     </term>
d738 1
a738 3
     <term>
      <literal>\dT</literal>
     </term>
d746 2
a747 4
    <varlistentry>
     <term>
      <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ]
     </term>
d757 1
a757 3
     <term>
      <literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ]
     </term>
d768 1
a768 3
     <term>
      <literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ]
     </term>
d777 1
a777 3
     <term>
      <literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
     </term>
d789 1
a789 3
     <term>
      <literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ]
     </term>
d806 1
a806 3
     <term>
      <literal>\H</literal>
     </term>
d817 1
a817 3
     <term>
      <literal>\i</literal> <replaceable class="parameter">filename</replaceable>
     </term>
d827 1
a827 3
     <term>
      <literal>\l</literal>
     </term>
d836 1
a836 3
     <term>
      <literal>\m</literal>
     </term>
d849 1
a849 3
     <term>
      <literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
     </term>
d863 1
a863 3
     <term>
      <literal>\p</literal>
     </term>
d872 1
a872 3
     <term>
      <literal>\q</literal>
     </term>
d881 1
a881 3
     <term>
      <literal>\r</literal>
     </term>
d890 1
a890 3
     <term>
      <literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]
     </term>
d904 1
a904 3
     <term>
      <literal>\t</literal>
     </term>
d913 1
a913 3
     <term>
      <literal>\T</literal> <replaceable class="parameter">table_options</replaceable>
     </term>
d927 1
a927 3
     <term>
      <literal>\x</literal>
     </term>
d939 1
a939 3
     <term>
      <literal>\w</literal> <replaceable class="parameter">filename</replaceable>
     </term>
d949 1
a949 3
     <term>
      <literal>\z</literal>
     </term>
d959 1
a959 3
     <term>
      <literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]
     </term>
d969 1
a969 3
     <term>
      <literal>\?</literal>
     </term>
d993 1
a993 1
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
@


1.7
log
@Add reference pages on user interface applications.
@
text
@d1 3
a3 3
<REFENTRY ID="APP-PSQL">
 <REFMETA>
  <REFENTRYTITLE id="psql-ref">
d5 5
a9 5
  </REFENTRYTITLE>
  <REFMISCINFO>Application</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
d11 2
a12 2
  </REFNAME>
  <REFPURPOSE>
d14 1
a14 1
  </REFPURPOSE>
d16 5
a20 5
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-26</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
d23 13
a35 9
    -e -E [ -f <replaceable class="parameter">filename</replaceable> ] [ -F <replaceable class="parameter">separator</replaceable> ] [ -h <replaceable class="parameter">hostname</replaceable> ] -Hln
    [ -o <replaceable class="parameter">filename</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] -qsSt ] [ -T <replaceable class="parameter">table_options</replaceable> ] -ux [ <replaceable class="parameter">dbname</replaceable> ]
  </SYNOPSIS>

  <REFSECT2 ID="R2-APP-PSQL-1">
   <REFSECT2INFO>
    <DATE>1998-09-26</DATE>
   </REFSECT2INFO>
   <TITLE>
d37 2
a38 2
   </TITLE>
   <PARA>
d44 7
a50 7
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
       <REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE>
      </TERM>
      <LISTITEM>
       <PARA>
d57 3
a59 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d61 2
a62 2
     <VARLISTENTRY>
      <TERM>
d64 3
a66 3
      </TERM>
      <LISTITEM>
       <PARA>
d68 3
a70 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d92 3
a94 3
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
d96 3
a98 3
      </TERM>
      <LISTITEM>
       <PARA>
d103 3
a105 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d107 2
a108 2
     <VARLISTENTRY>
      <TERM>
d110 3
a112 3
      </TERM>
      <LISTITEM>
       <PARA>
d115 3
a117 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d119 2
a120 2
     <VARLISTENTRY>
      <TERM>
d122 3
a124 3
      </TERM>
      <LISTITEM>
       <PARA>
d127 3
a129 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d131 2
a132 2
     <VARLISTENTRY>
      <TERM>
d134 3
a136 3
      </TERM>
      <LISTITEM>
       <PARA>
d141 3
a143 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d145 2
a146 2
     <VARLISTENTRY>
      <TERM>
d148 3
a150 3
      </TERM>
      <LISTITEM>
       <PARA>
d168 5
a172 5
  <REFSECT2 ID="R2-APP-PSQL-2">
   <REFSECT2INFO>
    <DATE>1998-09-26</DATE>
   </REFSECT2INFO>
   <TITLE>
d174 2
a175 2
   </TITLE>
   <PARA>
d187 5
a191 5
 <REFSECT1 ID="R1-APP-PSQL-1">
  <REFSECT1INFO>
   <DATE>1998-09-26</DATE>
  </REFSECT1INFO>
  <TITLE>
d193 2
a194 2
  </TITLE>
  <PARA>
d227 5
a231 5
  <REFSECT2 ID="R2-APP-PSQL-3">
   <REFSECT2INFO>
    <DATE>1998-09-26</DATE>
   </REFSECT2INFO>
   <TITLE>
d233 1
a233 1
   </TITLE>
d249 5
a253 5
  <REFSECT2 ID="R2-APP-PSQL-4">
   <REFSECT2INFO>
    <DATE>1998-09-26</DATE>
   </REFSECT2INFO>
   <TITLE>
d255 1
a255 1
   </TITLE>
d295 1
a295 1
   <Title>Paging To Screen</Title>
d297 3
a299 3
   <Note>
    <Title>Author</Title>
    <Para>
d301 2
a302 2
    </Para>
   </Note>
d304 2
a305 2
   <Para>
    To affect the paging behavior of your <Command>psql</Command> output,
d311 1
a311 1
   <Para>
d314 1
a314 1
    <ProgramListing>
d316 1
a316 1
    </ProgramListing>
d320 1
a320 1
    <ProgramListing>
d322 1
a322 1
    </ProgramListing>
d327 5
a331 5
 <REFSECT1 ID="R1-APP-PSQL-2">
  <REFSECT1INFO>
   <DATE>1998-09-26</DATE>
  </REFSECT1INFO>
  <TITLE>
d333 1
a333 1
  </TITLE>
d338 3
a340 3
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
d342 3
a344 3
     </TERM>
     <LISTITEM>
      <PARA>
d350 2
a351 2
    <VARLISTENTRY>
     <TERM>
d353 3
a355 3
     </TERM>
     <LISTITEM>
      <PARA>
d366 2
a367 2
    <VARLISTENTRY>
     <TERM>
d369 3
a371 3
     </TERM>
     <LISTITEM>
      <PARA>
d379 2
a380 2
    <VARLISTENTRY>
     <TERM>
d382 3
a384 3
     </TERM>
     <LISTITEM>
      <PARA>
d390 2
a391 2
    <VARLISTENTRY>
     <TERM>
d393 3
a395 3
     </TERM>
     <LISTITEM>
      <PARA>
d401 2
a402 2
    <VARLISTENTRY>
     <TERM>
d404 3
a406 3
     </TERM>
     <LISTITEM>
      <PARA>
d414 2
a415 2
    <VARLISTENTRY>
     <TERM>
d417 3
a419 3
     </TERM>
     <LISTITEM>
      <PARA>
d427 2
a428 2
    <VARLISTENTRY>
     <TERM>
d430 3
a432 3
     </TERM>
     <LISTITEM>
      <PARA>
d442 2
a443 2
    <VARLISTENTRY>
     <TERM>
d445 3
a447 3
     </TERM>
     <LISTITEM>
      <PARA>
d455 2
a456 2
    <VARLISTENTRY>
     <TERM>
d458 3
a460 3
     </TERM>
     <LISTITEM>
      <PARA>
d466 2
a467 2
    <VARLISTENTRY>
     <TERM>
d469 3
a471 3
     </TERM>
     <LISTITEM>
      <PARA>
d477 2
a478 2
    <VARLISTENTRY>
     <TERM>
d480 3
a482 3
     </TERM>
     <LISTITEM>
      <PARA>
d489 2
a490 2
    <VARLISTENTRY>
     <TERM>
d492 3
a494 3
     </TERM>
     <LISTITEM>
      <PARA>
d505 2
a506 2
    <VARLISTENTRY>
     <TERM>
d508 3
a510 3
     </TERM>
     <LISTITEM>
      <PARA>
d522 2
a523 2
    <VARLISTENTRY>
     <TERM>
d525 3
a527 3
     </TERM>
     <LISTITEM>
      <PARA>
d534 2
a535 2
    <VARLISTENTRY>
     <TERM>
d537 3
a539 3
     </TERM>
     <LISTITEM>
      <PARA>
d546 2
a547 2
    <VARLISTENTRY>
     <TERM>
d549 3
a551 3
     </TERM>
     <LISTITEM>
      <PARA>
d560 2
a561 2
    <VARLISTENTRY>
     <TERM>
d563 3
a565 3
     </TERM>
     <LISTITEM>
      <PARA>
d575 2
a576 2
    <VARLISTENTRY>
     <TERM>
d578 3
a580 3
     </TERM>
     <LISTITEM>
      <PARA>
d590 2
a591 2
    <VARLISTENTRY>
     <TERM>
d593 3
a595 3
     </TERM>
     <LISTITEM>
      <PARA>
d611 5
a615 5
 <REFSECT1 ID="R1-APP-PSQL-3">
  <REFSECT1INFO>
   <DATE>1998-09-26</DATE>
  </REFSECT1INFO>
  <TITLE>
d617 1
a617 1
  </TITLE>
d625 1
a625 1
   <Application>psql</Application> meta-commands are also called slash commands.
d641 3
a643 3
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
d645 3
a647 3
     </TERM>
     <LISTITEM>
      <PARA>
d653 2
a654 2
    <VARLISTENTRY>
     <TERM>
d656 3
a658 3
     </TERM>
     <LISTITEM>
      <PARA>
d665 7
a671 6
    <VARLISTENTRY>
     <TERM>
      <literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ]
     </TERM>
     <LISTITEM>
      <PARA>
d679 7
a685 6
    <VARLISTENTRY>
     <TERM>
      <literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable>
     </TERM>
     <LISTITEM>
      <PARA>
d690 2
a691 1
       file and routes the data to or from the backend.  The default <literal>tab</literal>
d705 2
a706 2
    <VARLISTENTRY>
     <TERM>
d708 5
a712 4
     </TERM>
     <LISTITEM>
      <PARA>
       List tables in the database, or if <replaceable class="parameter">table</replaceable>
d720 2
a721 2
    <VARLISTENTRY>
     <TERM>
d723 3
a725 3
     </TERM>
     <LISTITEM>
      <PARA>
d731 2
a732 2
    <VARLISTENTRY>
     <TERM>
d734 3
a736 3
     </TERM>
     <LISTITEM>
      <PARA>
d751 2
a752 2
    <VARLISTENTRY>
     <TERM>
d754 3
a756 3
     </TERM>
     <LISTITEM>
      <PARA>
d762 2
a763 2
    <VARLISTENTRY>
     <TERM>
d765 3
a767 3
     </TERM>
     <LISTITEM>
      <PARA>
d773 2
a774 2
    <VARLISTENTRY>
     <TERM>
d776 3
a778 3
     </TERM>
     <LISTITEM>
      <PARA>
d784 2
a785 2
    <VARLISTENTRY>
     <TERM>
d787 3
a789 3
     </TERM>
     <LISTITEM>
      <PARA>
d795 2
a796 2
    <VARLISTENTRY>
     <TERM>
d798 3
a800 3
     </TERM>
     <LISTITEM>
      <PARA>
d806 2
a807 2
    <VARLISTENTRY>
     <TERM>
d809 3
a811 3
     </TERM>
     <LISTITEM>
      <PARA>
d817 2
a818 2
    <VARLISTENTRY>
     <TERM>
d820 3
a822 3
     </TERM>
     <LISTITEM>
      <PARA>
d828 2
a829 2
    <VARLISTENTRY>
     <TERM>
d831 3
a833 3
     </TERM>
     <LISTITEM>
      <PARA>
d840 2
a841 2
    <VARLISTENTRY>
     <TERM>
d843 3
a845 3
     </TERM>
     <LISTITEM>
      <PARA>
d853 2
a854 2
    <VARLISTENTRY>
     <TERM>
d856 3
a858 3
     </TERM>
     <LISTITEM>
      <PARA>
d864 2
a865 2
    <VARLISTENTRY>
     <TERM>
d867 3
a869 3
     </TERM>
     <LISTITEM>
      <PARA>
d878 2
a879 2
    <VARLISTENTRY>
     <TERM>
d881 3
a883 3
     </TERM>
     <LISTITEM>
      <PARA>
d897 2
a898 2
    <VARLISTENTRY>
     <TERM>
d900 5
a904 4
     </TERM>
     <LISTITEM>
      <PARA>
       Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option>
d910 2
a911 2
    <VARLISTENTRY>
     <TERM>
d913 3
a915 3
     </TERM>
     <LISTITEM>
      <PARA>
d922 2
a923 2
    <VARLISTENTRY>
     <TERM>
d925 3
a927 3
     </TERM>
     <LISTITEM>
      <PARA>
d933 2
a934 2
    <VARLISTENTRY>
     <TERM>
d936 3
a938 3
     </TERM>
     <LISTITEM>
      <PARA>
d948 2
a949 2
    <VARLISTENTRY>
     <TERM>
d951 3
a953 3
     </TERM>
     <LISTITEM>
      <PARA>
d964 2
a965 2
    <VARLISTENTRY>
     <TERM>
d967 3
a969 3
     </TERM>
     <LISTITEM>
      <PARA>
d975 2
a976 2
    <VARLISTENTRY>
     <TERM>
d978 3
a980 3
     </TERM>
     <LISTITEM>
      <PARA>
d986 2
a987 2
    <VARLISTENTRY>
     <TERM>
d989 3
a991 3
     </TERM>
     <LISTITEM>
      <PARA>
d997 2
a998 2
    <VARLISTENTRY>
     <TERM>
d1000 3
a1002 3
     </TERM>
     <LISTITEM>
      <PARA>
d1013 2
a1014 2
    <VARLISTENTRY>
     <TERM>
d1016 3
a1018 3
     </TERM>
     <LISTITEM>
      <PARA>
d1024 2
a1025 2
    <VARLISTENTRY>
     <TERM>
d1027 3
a1029 3
     </TERM>
     <LISTITEM>
      <PARA>
d1040 2
a1041 2
    <VARLISTENTRY>
     <TERM>
d1043 3
a1045 3
     </TERM>
     <LISTITEM>
      <PARA>
d1054 2
a1055 2
    <VARLISTENTRY>
     <TERM>
d1057 3
a1059 3
     </TERM>
     <LISTITEM>
      <PARA>
d1066 2
a1067 2
    <VARLISTENTRY>
     <TERM>
d1069 3
a1071 3
     </TERM>
     <LISTITEM>
      <PARA>
d1078 2
a1079 2
    <VARLISTENTRY>
     <TERM>
d1081 3
a1083 3
     </TERM>
     <LISTITEM>
      <PARA>
d1090 2
a1091 2
    <VARLISTENTRY>
     <TERM>
d1093 3
a1095 3
     </TERM>
     <LISTITEM>
      <PARA>
@


1.6
log
@Add -E option
@
text
@d2 19
a20 19
<REFMETA>
<REFENTRYTITLE id="psql-ref">
<application>psql</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>psql</application>
</REFNAME>
<REFPURPOSE>
<productname>Postgres</productname> interactive client
</REFPURPOSE>
  </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-26</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
d25 1
a25 1
</SYNOPSIS>
d27 40
a66 30
    <REFSECT2 ID="R2-APP-PSQL-1">
      <REFSECT2INFO>
	<DATE>1998-09-26</DATE>
      </REFSECT2INFO>
      <TITLE>
	Inputs
      </TITLE>
      <PARA>
	<application>psql</application> accepts many command-line arguments,
	a rich set of meta-commands, and the full <acronym>SQL</acronym> language
	supported by <productname>Postgres</productname>. The most common
	command-line arguments are:
	
	<VARIABLELIST>
	  <VARLISTENTRY>
	    <TERM>
	      <REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		The name of an existing database to access.
		<replaceable class="parameter">dbname</replaceable>
		defaults to the value of the
		<envar>USER</envar>
		environment variable or, if that's not set, to the Unix account name of the
		current user.
		
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>
d68 200
a267 10
	  <VARLISTENTRY>
	    <TERM>
	      -c <replaceable class="parameter">query</replaceable>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		A single query to run. <application>psql</application> will exit on completion.
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>
d269 73
a341 1
	</variablelist>
d343 2
a344 17
      <para>
	The full set of command-line arguments and meta-commands are described in a subsequent
	section.
      </para>
      <para>
	There are some environment variables which can be used in liu of
	command line arguments. 
	Additionally, the <productname>Postgres</productname> frontend library used by 
	the <application>psql</application> application
	looks for other optional environment variables to configure, for example,
	the style of date/time representation and the local time zone. Refer
	to the chapter on <filename>libpq</filename> in the
	<citetitle>Programmer's Guide</citetitle> for more details.
      </para>
      <para>
	You may set any of the following environment variables to avoid
	specifying command-line options:
d346 740
a1085 83
	<VARIABLELIST>
	  <VARLISTENTRY>
	    <TERM>
	      <envar>PGHOST</envar>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		The <acronym>DNS</acronym> host name of the database server.
		Setting <envar>PGHOST</envar> to a non-zero-length string causes
		<acronym>TCP/IP</acronym> communication
		to be used, rather than the default local Unix domain sockets.
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>
	  
	  <VARLISTENTRY>
	    <TERM>
	      <envar>PGPORT</envar>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		The port number on which a <productname>Postgres</productname> server is listening.
		Defaults to <literal>5432</literal>.
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>
	  
	  <VARLISTENTRY>
	    <TERM>
	      <envar>PGTTY</envar>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		The target for display of messages from the client support library.
		Not required.
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>

	  <VARLISTENTRY>
	    <TERM>
	      <envar>PGOPTION</envar>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		If <envar>PGOPTION</envar>
		is specified, then the options it contains are parsed
		<emphasis>before</emphasis>
		any command-line options.
	      </PARA>
	    </LISTITEM>
	  </VARLISTENTRY>
	  
	  <VARLISTENTRY>
	    <TERM>
	      <envar>PGREALM</envar>
	    </TERM>
	    <LISTITEM>
	      <PARA>
		<envar>PGREALM</envar>
		only applies if
		<productname>Kerberos</productname>
		authentication is in use.  
		If this environment variable is set, <productname>Postgres</productname>
		will attempt authentication with servers for this realm and will use
		separate ticket files to avoid conflicts with local ticket files.
		See the <citetitle>PostgreSQL Administrator's Guide</citetitle>
		for additional information on
		<productname>Kerberos</productname>.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </para>
    </refsect2>

    <REFSECT2 ID="R2-APP-PSQL-2">
      <REFSECT2INFO>
	<DATE>1998-09-26</DATE>
      </REFSECT2INFO>
      <TITLE>
	Outputs
      </TITLE>
d1087 1
a1087 99
	
	<application>psql</application>
	returns 0 to the shell on successful completion of all queries,
	1 for errors, 2 for abrupt disconnection from the backend.
	The default TAB delimiter is used.
	<application>psql</application>
	will also return 1 if the connection to a database could not be made for
	any reason.
      </para>
    </refsect2>
  </refsynopsisdiv>
  
  <REFSECT1 ID="R1-APP-PSQL-1">
    <REFSECT1INFO>
      <DATE>1998-09-26</DATE>
    </REFSECT1INFO>
    <TITLE>
      Description
    </TITLE>
    <PARA>
      <application>psql</application> is a character-based front-end to 
      <productname>Postgres</productname>.
      It enables you to
      type in queries interactively, issue them to <productname>Postgres</productname>, 
      and see the query
      results.
    </para>
    <para>
      <application>psql</application>
      is a <productname>Postgres</productname> client application.  Hence, a
      <application>postmaster</application> process
      must be running on the database server host before
      <application>psql</application>
      is executed.  In addition, the correct parameters to identify
      the database server, such as the
      <application>postmaster</application> host name,
      may need to be specified
      as described below.
    </para>
    <para>
      When
      <application>psql</application>
      starts, it reads SQL commands from
      <filename>/etc/psqlrc</filename>
      and then from
      <filename>$(<envar>HOME</envar>)/.psqlrc</filename>
      This allows SQL commands like
      <command>SET</command>
      which can be used to set the date style to be run at the start of
      every session.
    </para>

    <REFSECT2 ID="R2-APP-PSQL-3">
      <REFSECT2INFO>
	<DATE>1998-09-26</DATE>
      </REFSECT2INFO>
      <TITLE>
	Connecting To A Database
      </TITLE>
      <para>
	<application>psql</application>
	attempts to make a connection to the database at the hostname and
	port number specified on the command line.   If the connection could not
	be made for any reason (e.g. insufficient privileges, postmaster is not
	running on the server, etc)
	.IR <application>psql</application>
	will return an error that says
	<programlisting>
	  Connection to database failed.
	</programlisting>
	The reason for the connection failure is not provided.
      </para>
    </refsect2>

    <REFSECT2 ID="R2-APP-PSQL-4">
      <REFSECT2INFO>
	<DATE>1998-09-26</DATE>
      </REFSECT2INFO>
      <TITLE>
	Entering Queries
      </TITLE>
      <para>
	In normal operation, 
	<application>psql</application> provides a prompt with the name of the
	database that <application>psql</application> is current connected to 
	followed by the string "=>".
	For example,
	<programlisting>
	  $ <userinput>psql testdb</userinput>
	  Welcome to the POSTGRESQL interactive sql monitor:
	  Please read the file COPYRIGHT for copyright terms of POSTGRESQL
	  
	  type \e? for help on slash commands
	  type \eq to quit
	  type \eg or terminate with semicolon to execute query
	  You are currently connected to the database: testdb
	  
	  testdb=>
	</programlisting>
d1089 5
a1093 790
      <para>
	At the prompt, the user may type in <acronym>SQL</acronym> queries.  
	Unless the -S option
	is set, input lines are sent to the backend when a query-terminating
	semicolon is reached.
      </para>
      <para>
	Whenever a query is executed, 
	<application>psql</application> also polls for asynchronous notification
	events generated by <command>LISTEN</command> and <command>NOTIFY</command>.
      </para>
      <para>
	<application>psql</application>
	can be used in a pipe sequence, and automatically detects when it
	is not listening or talking to a real tty.
      </para>
    </refsect2>
  </refsect1>

  <REFSECT1 ID="R1-APP-PSQL-2">
    <REFSECT1INFO>
      <DATE>1998-09-26</DATE>
    </REFSECT1INFO>
    <TITLE>
      Command-line Options
    </TITLE>
    <para>
      <application>psql</application>
      understands the following command-line options:

      <VARIABLELIST>
	<VARLISTENTRY>
	  <TERM>
	    -A
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Turn off fill justification when printing out table elements.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -c <replaceable class="parameter">query</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Specifies that
	      <application>psql</application>
	      is to execute one query string,
	      <replaceable class="parameter">query</replaceable>,
	      and then exit.  This is useful for shell scripts, typically in
	      conjunction with the <option>-q</option> option in shell scripts.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -d <replaceable class="parameter">dbname</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Specifies the name of the database to connect to. This is equivalent to specifying
	      <replaceable class="parameter">dbname</replaceable> as the last field in the
	      command line.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -e
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Echo the query sent to the backend
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    -E
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Echo the actual query generated by \d and other backslash commands
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    -f <replaceable class="parameter">filename</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Use the file <replaceable class="parameter">filename</replaceable>
	      as the source of queries instead of reading queries interactively.
	      This file must be specified for and visible to the client frontend.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -F <replaceable class="parameter">separator</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Use <replaceable class="parameter">separator</replaceable>
	      as the field separator.
	      The default is an ASCII vertical bar ("|").
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    -h <replaceable class="parameter">hostname</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Specifies the host name of the machine on which the
	      <application>postmaster</application>
	      is running.
	      Without this option, communication is performed using
	      local Unix domain sockets.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -H
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Turns on
	      <acronym>HTML 3.0</acronym>
	      tabular output.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -l
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Lists all available databases, then exit. Other non-connection options are ignored.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -n
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Do not use the readline library for input line editing and command history.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -o <replaceable class="parameter">filename</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Put all output into file <replaceable class="parameter">filename</replaceable>.
	      The path must be writable by the client.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -p <replaceable class="parameter">port</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Specifies the TCP/IP port or, by omission, the local Unix domain socket file
	      extension on which the
	      <application>postmaster</application>
	      is listening for connections.  Defaults to the value of the
	      <envar>PGPORT</envar>
	      environment variable, if set, or to 5432.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -q
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Specifies that
	      <application>psql</application>
	      should do its work quietly.  By default, it
	      prints welcome and exit messages and prompts for each query, and prints
	      out the number of rows returned from a query.
	      If this option is used, none of this happens. This is useful with the
	      <option>-c</option> option.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -s
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Run in single-step mode where the user is prompted for each query before
	      it is sent to the backend.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -S
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Runs in single-line mode where each query is terminated by a newline,
	      instead of a semicolon.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -t
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Turn off printing of column names.
	      This is useful with the
	      <option>-c</option>
	      option in shell scripts.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -T <replaceable class="parameter">table_options</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Allows you to specify options to be placed within the
	      <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym>
	      tabular output.For example, <literal>border</literal>
	      will give you tables with borders.
	      This must be used in conjunction with the <option>-H</option> option.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    -u
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Asks the user for the user name and password before connecting to the database.
	      If the database does not require password authentication then these are
	      ignored.  If the option is not used (and the PGPASSWORD environment variable
	      is not set) and the database requires password authentication, then the
	      connection will fail.  The user name is ignored anyway.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    -x
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Turns on extended row format mode. When enabled each row will have its column
	      names printed on the left with the column values printed on the right.
	      This is useful for rows which are otherwise too long to fit into
	      one screen line. HTML row output supports this mode also.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
    <para>
      You may set environment variables to avoid typing some of the above
      options.  See the section on environment variables below.
    </para>
  </refsect1>

  <REFSECT1 ID="R1-APP-PSQL-3">
    <REFSECT1INFO>
      <DATE>1998-09-26</DATE>
    </REFSECT1INFO>
    <TITLE>
      <application>psql</application> Meta-Commands
    </TITLE>
    <para>
      Anything you enter in <application>psql</application> 
      that begins with an unquoted backslash is a <application>psql</application>
      meta-command.  Anything else is <acronym>SQL</acronym>
      and simply goes into the current query buffer
      (and once you have at least one complete query, it gets automatically 
      submitted to the backend).  
      <Application>psql</Application> meta-commands are also called slash commands.
    </para>
    <para>
      The format of a <application>psql</application> command is the backslash, 
      followed immediately by
      a command verb, then any arguments.  The arguments are separated from the
      command verb and each other by any number of white space characters.
    </para>
    <para>
      With single character command verbs, you don't actually need to separate the
      command verb from the argument with white space, for historical reasons.
      You should anyway.
    </para>
    <para>
      The following meta-commands are defined:

      <VARIABLELIST>
	<VARLISTENTRY>
	  <TERM>
	    <literal>\a</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Toggle field alignment when printing out table elements.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\C</literal> <replaceable class="parameter">caption</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Set the HTML3.0 table caption to 
	      <quote><replaceable class="parameter">caption</replaceable></quote>.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Establish a connection to a new database, using the default 
	      <replaceable class="parameter">username</replaceable> if none is specified.
	      The previous connection is closed.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Perform a frontend (client) copy.  This is an operation that runs a SQL COPY command,
	      but instead of the backend reading or writing the specified file, and 
	      consequently requiring backend access and special user privilege, 
	      <application>psql</application> reads or writes the 
	      file and routes the data to or from the backend.  The default <literal>tab</literal>
	      delimiter is used.
	    </para>
	    <tip>
	      <para>
		This operation is not as efficient as the <acronym>SQL</acronym> 
		<command>COPY</command> command because all data must pass through the
		client/server IP or socket connection. For large amounts of data this other
		technique may be preferable.
	      </para>
	    </tip>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List tables in the database, or if <replaceable class="parameter">table</replaceable>
	      is specified, list the columns in that table.
	      If table name is specified as an asterisk (<quote>*</quote>),
	      list all tables and column information for each tables.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\da</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List all available aggregates.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\dd</literal> <replaceable class="parameter">object</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List the description from <literal>pg_description</literal>
	      of the specified object, which can be a
	      table, table.column, type, operator, or aggregate.
	    </para>
	    <tip>
	      <para>
		Not all objects have a description in <literal>pg_description</literal>.
		This meta-command can be useful to get a quick description of a native
		<productname>Postgres</productname> feature.
	      </para>
	    </tip>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\df</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List functions.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\di</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List only indexes.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\do</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List only operators.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\ds</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List only sequences.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\dS</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List system tables and indexes.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\dt</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List only non-system tables.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\dT</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List types.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Edit the current query buffer or the contents of the file
	      <replaceable class="parameter">filename</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Edit the current query buffer or the contents of the file
	      <replaceable class="parameter">filename</replaceable>
	      and execute it upon editor exit.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Set the field separator.  Default is a single blank space.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Send the current query input buffer to the backend and optionally
	      save the output in <replaceable class="parameter">filename</replaceable>
	      or pipe the output into a separate Unix shell to execute
	      <replaceable class="parameter">command</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Give syntax help on the specified SQL command.  
	      If <replaceable class="parameter">command</replaceable> is not a defined SQL command
	      (or is not documented in <application>psql</application>), or if
	      <replaceable class="parameter">command</replaceable> is not specified,
	      then <application>psql</application> will 
	      list all the commands for which syntax help is
	      available.  If <replaceable class="parameter">command</replaceable>
	      is an asterisk (<quote>*</quote>), then
	      give syntax help on all SQL commands.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\H</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option>
	      command-line option.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\i</literal> <replaceable class="parameter">filename</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Read queries from the file <replaceable class="parameter">filename</replaceable>
	      into the query input buffer.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\l</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      List all the databases in the server.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\m</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Toggle the old monitor-like table display, which includes border characters
	      surrounding the table.
	      This is standard SQL output.
	      By default, <application>psql</application> includes only field separators
	      between columns.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Save future query results to the file
	      <replaceable class="parameter">filename</replaceable> or pipe future
	      results into a separate Unix shell to execute
	      <replaceable class="parameter">command</replaceable>.
	      If no arguments are specified, send query results to
	      <filename>stdout</filename>.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\p</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Print the current query buffer.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\q</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Quit the <application>psql</application> program.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\r</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Reset(clear) the query buffer.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Print or save the command line history to 
	      <replaceable class="parameter">filename</replaceable>.
	      If <replaceable class="parameter">filename</replaceable> is omitted,
	      do not save subsequent commands to a history file.
	      This option is only available if <application>psql</application> is
	      configured to use readline.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\t</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Toggle display of output column name headings and row count footer (defaults to on).
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\T</literal> <replaceable class="parameter">table_options</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Allows you to specify options to be placed within the
	      <sgmltag>table ...</sgmltag> tag
	      for <acronym>HTML 3.0</acronym>
	      tabular output.For example, <literal>border</literal>
	      will give you tables with borders.
	      This must be used in conjunction with the <command>\H</command> meta-command.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\x</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Toggles extended row format mode. When enabled each row will have its column
	      names printed on the left with the column values printed on the right.
	      This is useful for rows which are otherwise too long to fit into
	      one screen line. <acronym>HTML</acronym> row output mode supports this flag too.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\w</literal> <replaceable class="parameter">filename</replaceable>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Outputs the current query buffer to the file
	      <replaceable class="parameter">filename</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>
	
	<VARLISTENTRY>
	  <TERM>
	    <literal>\z</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Produces a list of all tables in the database with their appropriate ACLs
	      (grant/revoke permissions) listed.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Escape to a separate Unix shell or execute the Unix command
	      <replaceable class="parameter">command</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>

	<VARLISTENTRY>
	  <TERM>
	    <literal>\?</literal>
	  </TERM>
	  <LISTITEM>
	    <PARA>
	      Get help information about the slash (<quote>\</quote>) commands.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
  </refsect1>
d1095 17
@


1.5
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
@d23 1
a23 1
    -e [ -f <replaceable class="parameter">filename</replaceable> ] [ -F <replaceable class="parameter">separator</replaceable> ] [ -h <replaceable class="parameter">hostname</replaceable> ] -Hln
d351 11
@


1.4
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
d27 1025
a1051 847
<REFSECT2 ID="R2-APP-PSQL-1">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>psql</application> accepts many command-line arguments,
a rich set of meta-commands, and the full <acronym>SQL</acronym> language
supported by <productname>Postgres</productname>. The most common
command-line arguments are:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">dbname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing database to access.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable or, if that's not set, to the Unix account name of the
current user.

</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
-c <replaceable class="parameter">query</replaceable>
</TERM>
<LISTITEM>
<PARA>
A single query to run. <application>psql</application> will exit on completion.
</PARA>
</LISTITEM>
</VARLISTENTRY>

</variablelist>

<para>
The full set of command-line arguments and meta-commands are described in a subsequent
section.

<para>
There are some environment variables which can be used in liu of
command line arguments. 
Additionally, the <productname>Postgres</productname> frontend library used by 
the <application>psql</application> application
looks for other optional environment variables to configure, for example,
the style of date/time representation and the local time zone. Refer
to the chapter on <filename>libpq</filename> in the
<citetitle>Programmer's Guide</citetitle> for more details.

<para>
You may set any of the following environment variables to avoid
specifying command-line options:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<envar>PGHOST</envar>
</TERM>
<LISTITEM>
<PARA>
The <acronym>DNS</acronym> host name of the database server.
Setting <envar>PGHOST</envar> to a non-zero-length string causes
<acronym>TCP/IP</acronym> communication
to be used, rather than the default local Unix domain sockets.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<envar>PGPORT</envar>
</TERM>
<LISTITEM>
<PARA>
The port number on which a <productname>Postgres</productname> server is listening.
Defaults to <literal>5432</literal>.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<envar>PGTTY</envar>
</TERM>
<LISTITEM>
<PARA>
The target for display of messages from the client support library.
Not required.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<envar>PGOPTION</envar>
</TERM>
<LISTITEM>
<PARA>
If <envar>PGOPTION</envar>
is specified, then the options it contains are parsed
<emphasis>before</emphasis>
any command-line options.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<envar>PGREALM</envar>
</TERM>
<LISTITEM>
<PARA>
<envar>PGREALM</envar>
only applies if
<productname>Kerberos</productname>
authentication is in use.  
If this environment variable is set, <productname>Postgres</productname>
will attempt authentication with servers for this realm and will use
separate ticket files to avoid conflicts with local ticket files.
See the <citetitle>PostgreSQL Administrator's Guide</citetitle>
for additional information on
<productname>Kerberos</productname>.

</variablelist>

<REFSECT2 ID="R2-APP-PSQL-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>

<application>psql</application>
returns 0 to the shell on successful completion of all queries,
1 for errors, 2 for abrupt disconnection from the backend.
The default TAB delimiter is used.
<application>psql</application>
will also return 1 if the connection to a database could not be made for
any reason.

<REFSECT1 ID="R1-APP-PSQL-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>psql</application> is a character-based front-end to 
<productname>Postgres</productname>.
It enables you to
type in queries interactively, issue them to <productname>Postgres</productname>, 
and see the query
results.

<para>
<application>psql</application>
is a <productname>Postgres</productname> client application.  Hence, a
<application>postmaster</application> process
 must be running on the database server host before
<application>psql</application>
is executed.  In addition, the correct parameters to identify
the database server, such as the
<application>postmaster</application> host name,
 may need to be specified
as described below.

<para>
When
<application>psql</application>
starts, it reads SQL commands from
<filename>/etc/psqlrc</filename>
and then from
<filename>$(<envar>HOME</envar>)/.psqlrc</filename>
This allows SQL commands like
<command>SET</command>
which can be used to set the date style to be run at the start of
every session.

<REFSECT2 ID="R2-APP-PSQL-3">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Connecting To A Database
</TITLE>
<para>
<application>psql</application>
attempts to make a connection to the database at the hostname and
port number specified on the command line.   If the connection could not
be made for any reason (e.g. insufficient privileges, postmaster is not
running on the server, etc)
.IR <application>psql</application>
will return an error that says
<programlisting>
Connection to database failed.
</programlisting>
The reason for the connection failure is not provided.

<REFSECT2 ID="R2-APP-PSQL-4">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Entering Queries
</TITLE>
<para>
In normal operation, 
<application>psql</application> provides a prompt with the name of the
database that <application>psql</application> is current connected to 
followed by the string "=>".
For example,
<programlisting>
$ <userinput>psql testdb</userinput>
Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL

   type \e? for help on slash commands
   type \eq to quit
   type \eg or terminate with semicolon to execute query
 You are currently connected to the database: testdb

testdb=>
</programlisting>

<para>
At the prompt, the user may type in <acronym>SQL</acronym> queries.  
Unless the -S option
is set, input lines are sent to the backend when a query-terminating
semicolon is reached.

<para>
Whenever a query is executed, 
<application>psql</application> also polls for asynchronous notification
events generated by <command>LISTEN</command> and <command>NOTIFY</command>.

<para>
<application>psql</application>
can be used in a pipe sequence, and automatically detects when it
is not listening or talking to a real tty.

<REFSECT1 ID="R1-APP-PSQL-2">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Command-line Options
</TITLE>
<para>
<application>psql</application>
understands the following command-line options:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
-A
</TERM>
<LISTITEM>
<PARA>
Turn off fill justification when printing out table elements.

<VARLISTENTRY>
<TERM>
-c <replaceable class="parameter">query</replaceable>
</TERM>
<LISTITEM>
<PARA>
Specifies that
<application>psql</application>
is to execute one query string,
<replaceable class="parameter">query</replaceable>,
and then exit.  This is useful for shell scripts, typically in
conjunction with the <option>-q</option> option in shell scripts.

<VARLISTENTRY>
<TERM>
-d <replaceable class="parameter">dbname</replaceable>
</TERM>
<LISTITEM>
<PARA>
Specifies the name of the database to connect to. This is equivalent to specifying
<replaceable class="parameter">dbname</replaceable> as the last field in the
command line.

<VARLISTENTRY>
<TERM>
-e
</TERM>
<LISTITEM>
<PARA>
Echo the query sent to the backend

<VARLISTENTRY>
<TERM>
-f <replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
Use the file <replaceable class="parameter">filename</replaceable>
as the source of queries instead of reading queries interactively.
This file must be specified for and visible to the client frontend.

<VARLISTENTRY>
<TERM>
-F <replaceable class="parameter">separator</replaceable>
</TERM>
<LISTITEM>
<PARA>
Use <replaceable class="parameter">separator</replaceable>
as the field separator.
The default is an ASCII vertical bar ("|").

<VARLISTENTRY>
<TERM>
-h <replaceable class="parameter">hostname</replaceable>
</TERM>
<LISTITEM>
<PARA>
Specifies the host name of the machine on which the
<application>postmaster</application>
is running.
Without this option, communication is performed using
local Unix domain sockets.

<VARLISTENTRY>
<TERM>
-H
</TERM>
<LISTITEM>
<PARA>
Turns on
<acronym>HTML 3.0</acronym>
tabular output.

<VARLISTENTRY>
<TERM>
-l
</TERM>
<LISTITEM>
<PARA>
Lists all available databases, then exit. Other non-connection options are ignored.

<VARLISTENTRY>
<TERM>
-n
</TERM>
<LISTITEM>
<PARA>
Do not use the readline library for input line editing and command history.

<VARLISTENTRY>
<TERM>
-o <replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
Put all output into file <replaceable class="parameter">filename</replaceable>.
The path must be writable by the client.

<VARLISTENTRY>
<TERM>
-p <replaceable class="parameter">port</replaceable>
</TERM>
<LISTITEM>
<PARA>
Specifies the TCP/IP port or, by omission, the local Unix domain socket file
extension on which the
<application>postmaster</application>
is listening for connections.  Defaults to the value of the
<envar>PGPORT</envar>
environment variable, if set, or to 5432.

<VARLISTENTRY>
<TERM>
-q
</TERM>
<LISTITEM>
<PARA>
Specifies that
<application>psql</application>
should do its work quietly.  By default, it
prints welcome and exit messages and prompts for each query, and prints
out the number of rows returned from a query.
If this option is used, none of this happens. This is useful with the
<option>-c</option> option.

<VARLISTENTRY>
<TERM>
-s
</TERM>
<LISTITEM>
<PARA>
Run in single-step mode where the user is prompted for each query before
it is sent to the backend.

<VARLISTENTRY>
<TERM>
-S
</TERM>
<LISTITEM>
<PARA>
Runs in single-line mode where each query is terminated by a newline,
instead of a semicolon.

<VARLISTENTRY>
<TERM>
-t
</TERM>
<LISTITEM>
<PARA>
Turn off printing of column names.
This is useful with the
<option>-c</option>
option in shell scripts.

<VARLISTENTRY>
<TERM>
-T <replaceable class="parameter">table_options</replaceable>
</TERM>
<LISTITEM>
<PARA>
Allows you to specify options to be placed within the
 <sgmltag>table ...</sgmltag> tag for <acronym>HTML 3.0</acronym>
tabular output.For example, <literal>border</literal>
will give you tables with borders.
This must be used in conjunction with the <option>-H</option> option.

<VARLISTENTRY>
<TERM>
-u
</TERM>
<LISTITEM>
<PARA>
Asks the user for the user name and password before connecting to the database.
If the database does not require password authentication then these are
ignored.  If the option is not used (and the PGPASSWORD environment variable
is not set) and the database requires password authentication, then the
connection will fail.  The user name is ignored anyway.

<VARLISTENTRY>
<TERM>
-x
</TERM>
<LISTITEM>
<PARA>
Turns on extended row format mode. When enabled each row will have its column
names printed on the left with the column values printed on the right.
This is useful for rows which are otherwise too long to fit into
one screen line. HTML row output supports this mode also.
</variablelist>

<para>
You may set environment variables to avoid typing some of the above
options.  See the section on environment variables below.


<REFSECT1 ID="R1-APP-PSQL-3">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
<application>psql</application> Meta-Commands
</TITLE>
<para>
Anything you enter in <application>psql</application> 
that begins with an unquoted backslash is a <application>psql</application>
meta-command.  Anything else is <acronym>SQL</acronym>
 and simply goes into the current query buffer
(and once you have at least one complete query, it gets automatically 
submitted to the backend).  
<Application>psql</Application> meta-commands are also called slash commands.

<para>
The format of a <application>psql</application> command is the backslash, 
followed immediately by
a command verb, then any arguments.  The arguments are separated from the
command verb and each other by any number of white space characters.

<para>
With single character command verbs, you don't actually need to separate the
command verb from the argument with white space, for historical reasons.
You should anyway.

<para>
The following meta-commands are defined:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<literal>\a</literal>
</TERM>
<LISTITEM>
<PARA>
Toggle field alignment when printing out table elements.

<VARLISTENTRY>
<TERM>
<literal>\C</literal> <replaceable class="parameter">caption</replaceable>
</TERM>
<LISTITEM>
<PARA>
Set the HTML3.0 table caption to 
<quote><replaceable class="parameter">caption</replaceable></quote>.

<VARLISTENTRY>
<TERM>
<literal>\connect</literal> <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Establish a connection to a new database, using the default 
<replaceable class="parameter">username</replaceable> if none is specified.
The previous connection is closed.

<VARLISTENTRY>
<TERM>
<literal>\copy</literal> <replaceable class="parameter">dbname</replaceable> { FROM | TO } <replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
Perform a frontend (client) copy.  This is an operation that runs a SQL COPY command,
but instead of the backend reading or writing the specified file, and 
consequently requiring backend access and special user privilege, 
<application>psql</application> reads or writes the 
file and routes the data to or from the backend.  The default <literal>tab</literal>
delimiter is used.
<tip>
<para>
This operation is not as efficient as the <acronym>SQL</acronym> 
<command>COPY</command> command because all data must pass through the
client/server IP or socket connection. For large amounts of data this other
technique may be preferable.
</tip>

<VARLISTENTRY>
<TERM>
<literal>\d</literal> [ <replaceable class="parameter">table</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
List tables in the database, or if <replaceable class="parameter">table</replaceable>
is specified, list the columns in that table.
If table name is specified as an asterisk (<quote>*</quote>),
list all tables and column information for each tables.

<VARLISTENTRY>
<TERM>
<literal>\da</literal>
</TERM>
<LISTITEM>
<PARA>
List all available aggregates.

<VARLISTENTRY>
<TERM>
<literal>\dd</literal> <replaceable class="parameter">object</replaceable>
</TERM>
<LISTITEM>
<PARA>
List the description from <literal>pg_description</literal>
of the specified object, which can be a
table, table.column, type, operator, or aggregate.
<tip>
<para>
Not all objects have a description in <literal>pg_description</literal>.
This meta-command can be useful to get a quick description of a native
<productname>Postgres</productname> feature.
</tip>

<VARLISTENTRY>
<TERM>
<literal>\df</literal>
</TERM>
<LISTITEM>
<PARA>
List functions.

<VARLISTENTRY>
<TERM>
<literal>\di</literal>
</TERM>
<LISTITEM>
<PARA>
List only indexes.

<VARLISTENTRY>
<TERM>
<literal>\do</literal>
</TERM>
<LISTITEM>
<PARA>
List only operators.

<VARLISTENTRY>
<TERM>
<literal>\ds</literal>
</TERM>
<LISTITEM>
<PARA>
List only sequences.

<VARLISTENTRY>
<TERM>
<literal>\dS</literal>
</TERM>
<LISTITEM>
<PARA>
List system tables and indexes.

<VARLISTENTRY>
<TERM>
<literal>\dt</literal>
</TERM>
<LISTITEM>
<PARA>
List only non-system tables.

<VARLISTENTRY>
<TERM>
<literal>\dT</literal>
</TERM>
<LISTITEM>
<PARA>
List types.

<VARLISTENTRY>
<TERM>
<literal>\e</literal> [ <replaceable class="parameter">filename</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Edit the current query buffer or the contents of the file
<replaceable class="parameter">filename</replaceable>.

<VARLISTENTRY>
<TERM>
<literal>\E</literal> [ <replaceable class="parameter">filename</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Edit the current query buffer or the contents of the file
<replaceable class="parameter">filename</replaceable>
and execute it upon editor exit.

<VARLISTENTRY>
<TERM>
<literal>\f</literal> [ <replaceable class="parameter">separator</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Set the field separator.  Default is a single blank space.

<VARLISTENTRY>
<TERM>
<literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
</TERM>
<LISTITEM>
<PARA>
Send the current query input buffer to the backend and optionally
save the output in <replaceable class="parameter">filename</replaceable>
or pipe the output into a separate Unix shell to execute
<replaceable class="parameter">command</replaceable>.

<VARLISTENTRY>
<TERM>
<literal>\h</literal> [ <replaceable class="parameter">command</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Give syntax help on the specified SQL command.  
If <replaceable class="parameter">command</replaceable> is not a defined SQL command
(or is not documented in <application>psql</application>), or if
<replaceable class="parameter">command</replaceable> is not specified,
then <application>psql</application> will 
list all the commands for which syntax help is
available.  If <replaceable class="parameter">command</replaceable>
is an asterisk (<quote>*</quote>), then
give syntax help on all SQL commands.

<VARLISTENTRY>
<TERM>
<literal>\H</literal>
</TERM>
<LISTITEM>
<PARA>
Toggle <acronym>HTML3</acronym> output. This is equivalent to the <option>-H</option>
command-line option.

<VARLISTENTRY>
<TERM>
<literal>\i</literal> <replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
Read queries from the file <replaceable class="parameter">filename</replaceable>
into the query input buffer.

<VARLISTENTRY>
<TERM>
<literal>\l</literal>
</TERM>
<LISTITEM>
<PARA>
List all the databases in the server.

<VARLISTENTRY>
<TERM>
<literal>\m</literal>
</TERM>
<LISTITEM>
<PARA>
Toggle the old monitor-like table display, which includes border characters
surrounding the table.
This is standard SQL output.
By default, <application>psql</application> includes only field separators
between columns.

<VARLISTENTRY>
<TERM>
<literal>\o</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]
</TERM>
<LISTITEM>
<PARA>
Save future query results to the file
<replaceable class="parameter">filename</replaceable> or pipe future
results into a separate Unix shell to execute
<replaceable class="parameter">command</replaceable>.
If no arguments are specified, send query results to
<filename>stdout</filename>.

<VARLISTENTRY>
<TERM>
<literal>\p</literal>
</TERM>
<LISTITEM>
<PARA>
Print the current query buffer.

<VARLISTENTRY>
<TERM>
<literal>\q</literal>
</TERM>
<LISTITEM>
<PARA>
Quit the <application>psql</application> program.

<VARLISTENTRY>
<TERM>
<literal>\r</literal>
</TERM>
<LISTITEM>
<PARA>
Reset(clear) the query buffer.

<VARLISTENTRY>
<TERM>
<literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Print or save the command line history to 
<replaceable class="parameter">filename</replaceable>.
If <replaceable class="parameter">filename</replaceable> is omitted,
do not save subsequent commands to a history file.
This option is only available if <application>psql</application> is
configured to use readline.

<VARLISTENTRY>
<TERM>
<literal>\t</literal>
</TERM>
<LISTITEM>
<PARA>
Toggle display of output column name headings and row count footer (defaults to on).

<VARLISTENTRY>
<TERM>
<literal>\T</literal> <replaceable class="parameter">table_options</replaceable>
</TERM>
<LISTITEM>
<PARA>
Allows you to specify options to be placed within the
 <sgmltag>table ...</sgmltag> tag
for <acronym>HTML 3.0</acronym>
tabular output.For example, <literal>border</literal>
will give you tables with borders.
This must be used in conjunction with the <command>\H</command> meta-command.

<VARLISTENTRY>
<TERM>
<literal>\x</literal>
</TERM>
<LISTITEM>
<PARA>
Toggles extended row format mode. When enabled each row will have its column
names printed on the left with the column values printed on the right.
This is useful for rows which are otherwise too long to fit into
one screen line. <acronym>HTML</acronym> row output mode supports this flag too.

<VARLISTENTRY>
<TERM>
<literal>\w</literal> <replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
Outputs the current query buffer to the file
<replaceable class="parameter">filename</replaceable>.

<VARLISTENTRY>
<TERM>
<literal>\z</literal>
</TERM>
<LISTITEM>
<PARA>
Produces a list of all tables in the database with their appropriate ACLs
(grant/revoke permissions) listed.

<VARLISTENTRY>
<TERM>
<literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]
</TERM>
<LISTITEM>
<PARA>
Escape to a separate Unix shell or execute the Unix command
<replaceable class="parameter">command</replaceable>.

<VARLISTENTRY>
<TERM>
<literal>\?</literal>
</TERM>
<LISTITEM>
<PARA>
Get help information about the slash (<quote>\</quote>) commands.

</variablelist>

@


1.3
log
@SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
@
text
@d3 1
a3 1
<REFENTRYTITLE>
d9 1
a9 1
<REFNAME id="psql-ref">
d71 1
a71 1
The full set of command-line arguments and meta-commands are described in a following
d109 2
d121 2
d135 1
a135 1
.BR before
@


1.2
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
@d168 1
d869 1
a869 1
</refentry>@


1.1
log
@Add new SQL reference page and the first utility/app reference page
 converted from the man page.
@
text
@d9 1
a9 1
<REFNAME>
a179 1

@
