~ubuntu-branches/ubuntu/quantal/postgresql-9.1/quantal-proposed

« back to all changes in this revision

Viewing changes to doc/src/sgml/man1/psql.1

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2011-12-02 14:39:18 UTC
  • mfrom: (12.1.1 sid)
  • Revision ID: package-import@ubuntu.com-20111202143918-1ftj0oo87w0y8m8d
* New upstream bug fix release:
  - Fix bugs in information_schema.referential_constraints view.
    This view was being insufficiently careful about matching the
    foreign-key constraint to the depended-on primary or unique key
    constraint. That could result in failure to show a foreign key
    constraint at all, or showing it multiple times, or claiming that
    it depends on a different constraint than the one it really does.
    Since the view definition is installed by initdb, merely upgrading
    will not fix the problem. If you need to fix this in an existing
    installation, you can (as a superuser) drop the information_schema
    schema then re-create it by sourcing
    "SHAREDIR/information_schema.sql". (Run pg_config --sharedir if
    you're uncertain where "SHAREDIR" is.) This must be repeated in
    each database to be fixed.
  - Make "contrib/citext"'s upgrade script fix collations of citext
    columns and indexes.
    Existing citext columns and indexes aren't correctly marked as
    being of a collatable data type during pg_upgrade from a pre-9.1
    server. That leads to operations on them failing with errors such
    as "could not determine which collation to use for string
    comparison". This change allows them to be fixed by the same script
    that upgrades the citext module into a proper 9.1 extension during
    CREATE EXTENSION citext FROM unpackaged.
    If you have a previously-upgraded database that is suffering from
    this problem, and you already ran the "CREATE EXTENSION" command,
    you can manually run (as superuser) the "UPDATE" commands found at
    the end of "SHAREDIR/extension/citext--unpackaged--1.0.sql". (Run
    pg_config --sharedir if you're uncertain where "SHAREDIR" is.)
  - Fix possible crash during "UPDATE" or "DELETE" that joins to the
    output of a scalar-returning function.
  - Fix incorrect replay of WAL records for GIN index updates.
  - Fix TOAST-related data corruption during CREATE TABLE dest AS
    SELECT - FROM src or INSERT INTO dest SELECT * FROM src.
  - Fix possible failures during hot standby startup.
  - Start hot standby faster when initial snapshot is incomplete.
  - Fix race condition during toast table access from stale syscache
    entries. The typical symptom was transient errors like "missing chunk
    number 0 for toast value NNNNN in pg_toast_2619", where the cited toast
    table would always belong to a system catalog.
  - Track dependencies of functions on items used in parameter default
    expressions. Previously, a referenced object could be dropped without
    having dropped or modified the function, leading to misbehavior when
    the function was used. Note that merely installing this update will not
    fix the missing dependency entries; to do that, you'd need to
    "CREATE OR REPLACE" each such function afterwards. If you have
    functions whose defaults depend on non-built-in objects, doing so
    is recommended.
  - Fix incorrect management of placeholder variables in nestloop joins.
    This bug is known to lead to "variable not found in subplan target
    list" planner errors, and could possibly result in wrong query
    output when outer joins are involved.
  - Fix window functions that sort by expressions involving aggregates.
  - Fix "MergeAppend child's targetlist doesn't match MergeAppend"
    planner errors.
  - Fix index matching for operators with both collatable and
    noncollatable inputs. In 9.1.0, an indexable operator that has a
    non-collatable left-hand input type and a collatable right-hand input
    type would not be recognized as matching the left-hand column's index.
    An example is the hstore ? text operator.
  - Allow inlining of set-returning SQL functions with multiple OUT
    parameters.
  - Don't trust deferred-unique indexes for join removal.
  - Make DatumGetInetP() unpack inet datums that have a 1-byte header,
    and add a new macro, DatumGetInetPP(), that does not.
  - Improve locale support in money type's input and output.
    Aside from not supporting all standard lc_monetary formatting
    options, the input and output functions were inconsistent, meaning
    there were locales in which dumped money values could not be
    re-read.
  - Don't let transform_null_equals affect CASE foo WHEN NULL ...
    constructs.  transform_null_equals is only supposed to affect foo =
    NULL expressions written directly by the user, not equality checks
    generated internally by this form of CASE.
  - Change foreign-key trigger creation order to better support
    self-referential foreign keys.
  - Fix IF EXISTS to work correctly in "DROP OPERATOR FAMILY".
  - Disallow dropping of an extension from within its own script.
  - Don't mark auto-generated types as extension members.
  - Cope with invalid pre-existing search_path settings during "CREATE
    EXTENSION".
  - Avoid floating-point underflow while tracking buffer allocation
    rate.
  - Prevent autovacuum transactions from running in serializable mode.
    Autovacuum formerly used the cluster-wide default transaction
    isolation level, but there is no need for it to use anything higher
    than READ COMMITTED, and using SERIALIZABLE could result in
    unnecessary delays for other processes.
  - Ensure walsender processes respond promptly to SIGTERM.
  - Exclude "postmaster.opts" from base backups.
  - Fix incorrect field alignment in ecpg's SQLDA area.
  - Preserve blank lines within commands in psql's command history.
    The former behavior could cause problems if an empty line was
    removed from within a string literal, for example.
  - Avoid platform-specific infinite loop in pg_dump.
  - Fix compression of plain-text output format in pg_dump.
    pg_dump has historically understood -Z with no -F switch to mean
    that it should emit a gzip-compressed version of its plain text
    output. Restore that behavior.
  - Fix pg_dump to dump user-defined casts between auto-generated
    types, such as table rowtypes.
  - Fix missed quoting of foreign server names in pg_dump.
  - Assorted fixes for pg_upgrade. Handle exclusion constraints correctly,
    avoid failures on Windows, don't complain about mismatched toast table
    names in 8.4 databases.
  - In PL/pgSQL, allow foreign tables to define row types.
  - Fix up conversions of PL/Perl functions' results.
    Restore the pre-9.1 behavior that PL/Perl functions returning void
    ignore the result value of their last Perl statement; 9.1.0 would
    throw an error if that statement returned a reference. Also, make
    sure it works to return a string value for a composite type, so
    long as the string meets the type's input format. In addition,
    throw errors for attempts to return Perl arrays or hashes when the
    function's declared result type is not an array or composite type,
    respectively. (Pre-9.1 versions rather uselessly returned strings
    like ARRAY(0x221a9a0) or HASH(0x221aa90) in such cases.)
  - Ensure PL/Perl strings are always correctly UTF8-encoded.
  - Use the preferred version of xsubpp to build PL/Perl, not
    necessarily the operating system's main copy.
  - Correctly propagate SQLSTATE in PL/Python exceptions.
  - Do not install PL/Python extension files for Python major versions
    other than the one built against.
  - Change all the "contrib" extension script files to report a useful
    error message if they are fed to psql. This should help teach people
    about the new method of using "CREATE EXTENSION" to load these files.
    In most cases, sourcing the scripts directly would fail anyway, but
    with harder-to-interpret messages.
  - Fix incorrect coding in "contrib/dict_int" and "contrib/dict_xsyn".
  - Remove "contrib/sepgsql" tests from the regular regression test
    mechanism. Since these tests require root privileges for setup, they're
    impractical to run automatically. Switch over to a manual approach
    instead, and provide a testing script to help with that.
  - Fix assorted errors in "contrib/unaccent"'s configuration file
    parsing.
  - Honor query cancel interrupts promptly in pgstatindex().
  - Revert unintentional enabling of WAL_DEBUG. Fortunately, as debugging
    tools go, this one is pretty cheap; but it's not intended to be enabled
    by default, so revert.
  - Ensure VPATH builds properly install all server header files.
  - Shorten file names reported in verbose error messages.
    Regular builds have always reported just the name of the C file
    containing the error message call, but VPATH builds formerly
    reported an absolute path name.
* debian/rules: Fix build failure for binary-indep-only builds.
  (Closes: #646079)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
'\" t
2
2
.\"     Title: psql
3
3
.\"    Author: The PostgreSQL Global Development Group
4
 
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
5
 
.\"      Date: 2011-09-22
6
 
.\"    Manual: PostgreSQL 9.1.1 Documentation
7
 
.\"    Source: PostgreSQL 9.1.1
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 2011-12-01
 
6
.\"    Manual: PostgreSQL 9.1.2 Documentation
 
7
.\"    Source: PostgreSQL 9.1.2
8
8
.\"  Language: English
9
9
.\"
10
 
.TH "PSQL" "1" "2011-09-22" "PostgreSQL 9.1.1" "PostgreSQL 9.1.1 Documentation"
 
10
.TH "PSQL" "1" "2011-12-01" "PostgreSQL 9.1.2" "PostgreSQL 9.1.2 Documentation"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * Define some portability stuff
 
13
.\" -----------------------------------------------------------------
 
14
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
15
.\" http://bugs.debian.org/507673
 
16
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 
17
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
18
.ie \n(.g .ds Aq \(aq
 
19
.el       .ds Aq '
11
20
.\" -----------------------------------------------------------------
12
21
.\" * set default formatting
13
22
.\" -----------------------------------------------------------------
63
72
psql
64
73
meta\-commands with this option\&. To achieve that, you could pipe the string into
65
74
psql, like this:
66
 
echo \(aq\ex \e\e SELECT * FROM foo;\(aq | psql\&. (\e\e
 
75
echo \*(Aq\ex \e\e SELECT * FROM foo;\*(Aq | psql\&. (\e\e
67
76
is the separator meta\-command\&.)
68
77
.sp
69
78
If the command string contains multiple SQL commands, they are processed in a single transaction, unless there are explicit
70
79
BEGIN/COMMIT
71
80
commands included in the string to divide it into multiple transactions\&. This is different from the behavior when the same string is fed to
72
 
psql\(aqs standard input\&.
 
81
psql\*(Aqs standard input\&.
73
82
.RE
74
83
.PP
75
84
\fB\-d \fR\fB\fIdbname\fR\fR, \fB\-\-dbname=\fR\fB\fIdbname\fR\fR
100
109
Echo the actual queries generated by
101
110
\ed
102
111
and other backslash commands\&. You can use this to study
103
 
psql\(aqs internal operations\&. This is equivalent to setting the variable
 
112
psql\*(Aqs internal operations\&. This is equivalent to setting the variable
104
113
\fIECHO_HIDDEN\fR
105
114
from within
106
115
psql\&.
124
133
Using this option is subtly different from writing
125
134
psql < \fIfilename\fR\&. In general, both will do what you expect, but using
126
135
\-f
127
 
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\(aqs input redirection is (in theory) guaranteed to yield exactly the same output you would have received had you entered everything by hand\&.
 
136
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\*(Aqs input redirection is (in theory) guaranteed to yield exactly the same output you would have received had you entered everything by hand\&.
128
137
.RE
129
138
.PP
130
139
\fB\-F \fR\fB\fIseparator\fR\fR, \fB\-\-field\-separator=\fR\fB\fIseparator\fR\fR
319
328
.RS 4
320
329
Do not read the start\-up file (neither the system\-wide
321
330
psqlrc
322
 
file nor the user\(aqs
 
331
file nor the user\*(Aqs
323
332
~/\&.psqlrc
324
333
file)\&.
325
334
.RE
371
380
psql
372
381
will connect via a Unix\-domain socket to a server on the local host, or via TCP/IP to
373
382
localhost
374
 
on machines that don\(aqt 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\&.
 
383
on machines that don\*(Aqt 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\&.
375
384
.PP
376
 
When the defaults aren\(aqt quite right, you can save yourself some typing by setting the environment variables
 
385
When the defaults aren\*(Aqt quite right, you can save yourself some typing by setting the environment variables
377
386
\fBPGDATABASE\fR,
378
387
\fBPGHOST\fR,
379
388
\fBPGPORT\fR
413
422
psql
414
423
sets the client encoding to
415
424
\(lqauto\(rq, which will detect the appropriate client encoding from the locale settings (\fBLC_CTYPE\fR
416
 
environment variable on Unix systems)\&. If this doesn\(aqt work out as expected, the client encoding can be overridden using the environment variable
 
425
environment variable on Unix systems)\&. If this doesn\*(Aqt work out as expected, the client encoding can be overridden using the environment variable
417
426
\fBPGCLIENTENCODING\fR\&.
418
427
.SS "Entering SQL Commands"
419
428
.PP
429
438
.\}
430
439
.nf
431
440
$ \fBpsql testdb\fR
432
 
psql (9\&.1\&.1)
 
441
psql (9\&.1\&.2)
433
442
Type "help" for help\&.
434
443
 
435
444
testdb=>
477
486
If an unquoted argument begins with a colon (:), it is taken as a
478
487
psql
479
488
variable and the value of the variable is used as the argument instead\&. If the variable name is surrounded by single quotes (e\&.g\&.
480
 
:\(aqvar\(aq), 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\&.
 
489
:\*(Aqvar\*(Aq), 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\&.
481
490
.PP
482
491
Arguments that are enclosed in backquotes (`) 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\&.
483
492
.PP
524
533
are omitted or specified as
525
534
\-, the value of that parameter from the previous connection is used\&. If there is no previous connection, the
526
535
libpq
527
 
default for the parameter\(aqs value is used\&.
 
536
default for the parameter\*(Aqs value is used\&.
528
537
.sp
529
538
If the connection attempt failed (wrong user name, access denied, etc\&.), the previous connection will only be kept if
530
539
psql
543
552
\ecd [ \fIdirectory\fR ]
544
553
.RS 4
545
554
Changes the current working directory to
546
 
\fIdirectory\fR\&. Without argument, changes to the current user\(aqs home directory\&.
 
555
\fIdirectory\fR\&. Without argument, changes to the current user\*(Aqs home directory\&.
547
556
.if n \{\
548
557
.sp
549
558
.\}
567
576
Outputs information about the current database connection\&.
568
577
.RE
569
578
.PP
570
 
\ecopy { \fItable\fR [ ( \fIcolumn_list\fR ) ] | ( \fIquery\fR ) } { from | to } { \fIfilename\fR | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] \(aq\fIcharacter\fR\(aq ] [ null [ as ] \(aq\fIstring\fR\(aq ] [ csv [ header ] [ quote [ as ] \(aq\fIcharacter\fR\(aq ] [ escape [ as ] \(aq\fIcharacter\fR\(aq ] [ force quote \fIcolumn_list\fR | * ] [ force not null \fIcolumn_list\fR ] ]
 
579
\ecopy { \fItable\fR [ ( \fIcolumn_list\fR ) ] | ( \fIquery\fR ) } { from | to } { \fIfilename\fR | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] \*(Aq\fIcharacter\fR\*(Aq ] [ null [ as ] \*(Aq\fIstring\fR\*(Aq ] [ csv [ header ] [ quote [ as ] \*(Aq\fIcharacter\fR\*(Aq ] [ escape [ as ] \*(Aq\fIcharacter\fR\*(Aq ] [ force quote \fIcolumn_list\fR | * ] [ force not null \fIcolumn_list\fR ] ]
571
580
.RS 4
572
581
Performs a frontend (client) copy\&. This is an operation that runs an
573
582
SQL
588
597
\e\&.
589
598
is read or the stream reaches
590
599
EOF\&. Output is sent to the same place as command output\&. To read/write from
591
 
psql\(aqs standard input or output, use
 
600
psql\*(Aqs standard input or output, use
592
601
pstdin
593
602
or
594
603
pstdout\&. This option is useful for populating tables in\-line within a SQL script file\&.
771
780
\fIpattern\fR
772
781
is specified, only those servers whose name matches the pattern are listed\&. If the form
773
782
\edes+
774
 
is used, a full description of each server is shown, including the server\(aqs ACL, type, version, and options\&.
 
783
is used, a full description of each server is shown, including the server\*(Aqs ACL, type, version, and options\&.
775
784
.RE
776
785
.PP
777
786
\edet[+] [ \fIpattern\fR ]
852
861
\fBTip\fR
853
862
.ps -1
854
863
.br
855
 
To look up functions taking arguments or returning values of a specific type, use your pager\(aqs search capability to scroll through the
 
864
To look up functions taking arguments or returning values of a specific type, use your pager\*(Aqs search capability to scroll through the
856
865
\edf
857
866
output\&.
858
867
.sp .5v
950
959
S
951
960
modifier to include system objects\&. If
952
961
+
953
 
is appended to the command name, each collation is listed with its associated description, if any\&. Note that only collations usable with the current database\(aqs encoding are shown, so the results may vary in different databases of the same installation\&.
 
962
is appended to the command name, each collation is listed with its associated description, if any\&. Note that only collations usable with the current database\*(Aqs encoding are shown, so the results may vary in different databases of the same installation\&.
954
963
.RE
955
964
.PP
956
965
\edp [ \fIpattern\fR ]
1149
1158
.PP
1150
1159
\eg [ { \fIfilename\fR | |\fIcommand\fR } ]
1151
1160
.RS 4
1152
 
Sends the current query input buffer to the server and optionally stores the query\(aqs output in
 
1161
Sends the current query input buffer to the server and optionally stores the query\*(Aqs output in
1153
1162
\fIfilename\fR
1154
1163
or pipes the output into a separate Unix shell executing
1155
1164
\fIcommand\fR\&. A bare
1244
1253
\fIloid\fR
1245
1254
from the database and writes it to
1246
1255
\fIfilename\fR\&. Note that this is subtly different from the server function
1247
 
\fBlo_export\fR, which acts with the permissions of the user that the database server runs as and on the server\(aqs file system\&.
 
1256
\fBlo_export\fR, which acts with the permissions of the user that the database server runs as and on the server\*(Aqs file system\&.
1248
1257
.if n \{\
1249
1258
.sp
1250
1259
.\}
1259
1268
.br
1260
1269
Use
1261
1270
\elo_list
1262
 
to find out the large object\(aqs
 
1271
to find out the large object\*(Aqs
1263
1272
OID\&.
1264
1273
.sp .5v
1265
1274
.RE
1275
1284
.RS 4
1276
1285
.\}
1277
1286
.nf
1278
 
foo=> \fB\elo_import \(aq/home/peter/pictures/photo\&.xcf\(aq \(aqa picture of me\(aq\fR
 
1287
foo=> \fB\elo_import \*(Aq/home/peter/pictures/photo\&.xcf\*(Aq \*(Aqa picture of me\*(Aq\fR
1279
1288
lo_import 152801
1280
1289
.fi
1281
1290
.if n \{\
1288
1297
.sp
1289
1298
Note that this command is subtly different from the server\-side
1290
1299
\fBlo_import\fR
1291
 
because it acts as the local user on the local file system, rather than the server\(aqs user and file system\&.
 
1300
because it acts as the local user on the local file system, rather than the server\*(Aqs user and file system\&.
1292
1301
.RE
1293
1302
.PP
1294
1303
\elo_list
1318
1327
.br
1319
1328
Use
1320
1329
\elo_list
1321
 
to find out the large object\(aqs
 
1330
to find out the large object\*(Aqs
1322
1331
OID\&.
1323
1332
.sp .5v
1324
1333
.RE
1430
1439
off
1431
1440
which will enable or disable expanded mode\&. If
1432
1441
\fIvalue\fR
1433
 
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\(aqt fit on the screen in the normal
 
1442
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\*(Aqt fit on the screen in the normal
1434
1443
\(lqhorizontal\(rq
1435
1444
mode\&.
1436
1445
.RE
1438
1447
fieldsep
1439
1448
.RS 4
1440
1449
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
1441
 
\epset fieldsep \(aq\et\(aq\&. The default field separator is
1442
 
\(aq|\(aq
 
1450
\epset fieldsep \*(Aq\et\*(Aq\&. The default field separator is
 
1451
\*(Aq|\*(Aq
1443
1452
(a vertical bar)\&.
1444
1453
.RE
1445
1454
.PP
1541
1550
null
1542
1551
.RS 4
1543
1552
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
1544
 
\epset null \(aq(null)\(aq\&.
 
1553
\epset null \*(Aq(null)\*(Aq\&.
1545
1554
.RE
1546
1555
.PP
1547
1556
numericlocale
1597
1606
output format\&. This could for example be
1598
1607
cellpadding
1599
1608
or
1600
 
bgcolor\&. Note that you probably don\(aqt want to specify
 
1609
bgcolor\&. Note that you probably don\*(Aqt want to specify
1601
1610
border
1602
1611
here, as that is already taken care of by
1603
1612
\epset border\&. If no
1669
1678
.RE
1670
1679
.RE
1671
1680
.PP
1672
 
\eq
 
1681
\eq or \equit
1673
1682
.RS 4
1674
1683
Quits the
1675
1684
psql
1676
 
program\&.
 
1685
program\&. In a script file, only execution of that script is terminated\&.
1677
1686
.RE
1678
1687
.PP
1679
1688
\eqecho \fItext\fR [ \&.\&.\&. ]
1898
1907
$
1899
1908
is automatically appended to your pattern)\&. Write
1900
1909
*
1901
 
at the beginning and/or end if you don\(aqt 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
 
1910
at the beginning and/or end if you don\*(Aqt 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
1902
1911
\edo)\&.
1903
1912
.RE
1904
1913
.SS "Advanced Features"
1959
1968
The arguments of
1960
1969
\eset
1961
1970
are subject to the same substitution rules as with other commands\&. Thus you can construct interesting references such as
1962
 
\eset :foo \(aqsomething\(aq
 
1971
\eset :foo \*(Aqsomething\*(Aq
1963
1972
and get
1964
1973
\(lqsoft links\(rq
1965
1974
or
1980
1989
\eunset\&.
1981
1990
.PP
1982
1991
 
1983
 
psql\(aqs 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
 
1992
psql\*(Aqs 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
1984
1993
psql\&. 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\&.
1985
1994
.PP
1986
1995
\fIAUTOCOMMIT\fR
2034
2043
.ps -1
2035
2044
.br
2036
2045
The autocommit\-on mode is
2037
 
PostgreSQL\(aqs 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
 
2046
PostgreSQL\*(Aqs 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
2038
2047
psqlrc
2039
2048
file or your
2040
2049
~/\&.psqlrc
2315
2324
.RS 4
2316
2325
.\}
2317
2326
.nf
2318
 
testdb=> \fB\eset foo \(aqmy_table\(aq\fR
 
2327
testdb=> \fB\eset foo \*(Aqmy_table\*(Aq\fR
2319
2328
testdb=> \fBSELECT * FROM :foo;\fR
2320
2329
.fi
2321
2330
.if n \{\
2331
2340
.RS 4
2332
2341
.\}
2333
2342
.nf
2334
 
testdb=> \fB\eset foo \(aqmy_table\(aq\fR
 
2343
testdb=> \fB\eset foo \*(Aqmy_table\*(Aq\fR
2335
2344
testdb=> \fBSELECT * FROM :"foo";\fR
2336
2345
.fi
2337
2346
.if n \{\
2349
2358
.\}
2350
2359
.nf
2351
2360
testdb=> \fB\eset content `cat my_file\&.txt`\fR
2352
 
testdb=> \fBINSERT INTO my_table VALUES (:\(aqcontent\(aq);\fR
 
2361
testdb=> \fBINSERT INTO my_table VALUES (:\*(Aqcontent\*(Aq);\fR
2353
2362
.fi
2354
2363
.if n \{\
2355
2364
.RE
2356
2365
.\}
2357
2366
.sp
2358
 
(Note that this still won\(aqt work if
 
2367
(Note that this still won\*(Aqt work if
2359
2368
my_file\&.txt
2360
2369
contains NUL bytes\&. psql does not support embedded NUL bytes in variable values\&.)
2361
2370
.PP
2362
2371
Since colons can legally appear in SQL commands, an apparent attempt at interpolation (such as
2363
2372
:name,
2364
 
:\(aqname\(aq, or
 
2373
:\*(Aqname\*(Aq, or
2365
2374
:"name") 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
2366
2375
SQL
2367
2376
for embedded query languages, such as
2368
2377
ECPG\&. The colon syntax for array slices and type casts are
2369
2378
PostgreSQL
2370
 
extensions, hence the conflict\&. The colon syntax for escaping a variable\(aqs value as an SQL literal or identifier is a
 
2379
extensions, hence the conflict\&. The colon syntax for escaping a variable\*(Aqs value as an SQL literal or identifier is a
2371
2380
psql
2372
2381
extension\&.)
2373
2382
.RE
2455
2464
\-,
2456
2465
*, a single quote, a double quote, or a dollar sign, depending on whether
2457
2466
psql
2458
 
expects more input because the command wasn\(aqt terminated yet, because you are inside a
 
2467
expects more input because the command wasn\*(Aqt terminated yet, because you are inside a
2459
2468
/* \&.\&.\&. */
2460
 
comment, or because you are inside a quoted or dollar\-escaped string\&. In prompt 3 the sequence doesn\(aqt produce anything\&.
 
2469
comment, or because you are inside a quoted or dollar\-escaped string\&. In prompt 3 the sequence doesn\*(Aqt produce anything\&.
2461
2470
.RE
2462
2471
.PP
2463
2472
%x
2507
2516
.RS 4
2508
2517
.\}
2509
2518
.nf
2510
 
testdb=> \eset PROMPT1 \(aq%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# \(aq
 
2519
testdb=> \eset PROMPT1 \*(Aq%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# \*(Aq
2511
2520
.fi
2512
2521
.if n \{\
2513
2522
.RE
2517
2526
.RE
2518
2527
To insert a percent sign into your prompt, write
2519
2528
%%\&. The default prompts are
2520
 
\(aq%/%R%# \(aq
 
2529
\*(Aq%/%R%# \*(Aq
2521
2530
for prompts 1 and 2, and
2522
 
\(aq>> \(aq
 
2531
\*(Aq>> \*(Aq
2523
2532
for prompt 3\&.
2524
2533
.if n \{\
2525
2534
.sp
2628
2637
\ee
2629
2638
or
2630
2639
\eef
2631
 
is used with a line number argument, this variable specifies the command\-line argument used to pass the starting line number to the user\(aqs editor\&. For editors such as
 
2640
is used with a line number argument, this variable specifies the command\-line argument used to pass the starting line number to the user\*(Aqs editor\&. For editors such as
2632
2641
Emacs
2633
2642
or
2634
2643
vi, this is a plus sign\&. Include a trailing space in the value of the variable if there needs to be space between the option name and the line number\&. Examples:
2637
2646
.RS 4
2638
2647
.\}
2639
2648
.nf
2640
 
PSQL_EDITOR_LINENUMBER_ARG=\(aq+\(aq
2641
 
PSQL_EDITOR_LINENUMBER_ARG=\(aq\-\-line \(aq
 
2649
PSQL_EDITOR_LINENUMBER_ARG=\*(Aq+\*(Aq
 
2650
PSQL_EDITOR_LINENUMBER_ARG=\*(Aq\-\-line \*(Aq
2642
2651
.fi
2643
2652
.if n \{\
2644
2653
.RE
2687
2696
psql
2688
2697
attempts to read and execute commands from the system\-wide
2689
2698
psqlrc
2690
 
file and the user\(aqs
 
2699
file and the user\*(Aqs
2691
2700
~/\&.psqlrc
2692
 
file before starting up\&. (On Windows, the user\(aqs startup file is named
 
2701
file before starting up\&. (On Windows, the user\*(Aqs startup file is named
2693
2702
%APPDATA%\epostgresql\epsqlrc\&.conf\&.) See
2694
2703
\fIPREFIX\fR/share/psqlrc\&.sample
2695
2704
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
2709
2718
.\}
2710
2719
Both the system\-wide
2711
2720
psqlrc
2712
 
file and the user\(aqs
 
2721
file and the user\*(Aqs
2713
2722
~/\&.psqlrc
2714
2723
file can be made version\-specific by appending a dash and the
2715
2724
PostgreSQL
2716
2725
release number, for example
2717
 
~/\&.psqlrc\-9\&.1\&.1\&. A matching version\-specific file will be read in preference to a non\-version\-specific file\&.
 
2726
~/\&.psqlrc\-9\&.1\&.2\&. A matching version\-specific file will be read in preference to a non\-version\-specific file\&.
2718
2727
.RE
2719
2728
.sp
2720
2729
.RS 4
2839
2848
.RS 4
2840
2849
.\}
2841
2850
.nf
2842
 
testdb=> \fB\eset PROMPT1 \(aq%n@%m %~%R%# \(aq\fR
 
2851
testdb=> \fB\eset PROMPT1 \*(Aq%n@%m %~%R%# \*(Aq\fR
2843
2852
peter@localhost testdb=>
2844
2853
.fi
2845
2854
.if n \{\
2846
2855
.RE
2847
2856
.\}
2848
2857
.sp
2849
 
Let\(aqs assume you have filled the table with data and want to take a look at it:
 
2858
Let\*(Aqs assume you have filled the table with data and want to take a look at it:
2850
2859
.sp
2851
2860
.if n \{\
2852
2861
.RS 4