@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.75 2002/09/18 20:09:32 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.76 2002/09/21 18:32:54 petere Exp $
PostgreSQL documentation
-->
@ -51,19 +51,21 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
<term>-a, --echo-all</term>
<term><option>-a</></term>
<term><option>--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 <en var>ECHO</en var> to
equivalent to setting the variable <varname >ECHO</varname > to
<literal>all</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-A, --no-align</term>
<term><option>-A</></term>
<term><option>--no-align</></term>
<listitem>
<para>
Switches to unaligned output mode. (The default output mode is
@ -73,7 +75,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-c, --command <replaceable class="parameter">query</replaceable></term>
<term><option>-c <replaceable class="parameter">query</replaceable></></term>
<term><option>--command <replaceable class="parameter">query</replaceable></></term>
<listitem>
<para>
Specifies that <application>psql</application> is to execute one
@ -82,7 +85,7 @@ PostgreSQL documentation
</para>
<para>
<replaceable class="parameter">query</replaceable> must be either
a query string that is completely parse able by the backend (i.e.,
a query string that is completely parsable 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>
@ -94,7 +97,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
<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
@ -106,31 +110,34 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-e, --echo-queries</term>
<term><option>-e</></term>
<term><option>--echo-queries</></term>
<listitem>
<para>
Show all queries that are sent to the backend. This is equivalent
to setting the variable <en var>ECHO</en var> to
to setting the variable <varname >ECHO</varname > to
<literal>queries</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-E, --echo-hidden</term>
<term><option>-E</></term>
<term><option>--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 <en var>ECHO_HIDDEN</en var> from within
setting the variable <varname >ECHO_HIDDEN</varname > from within
<application>psql</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f, --file <replaceable class="parameter">filename</replaceable></term>
<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>
@ -161,7 +168,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
<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
@ -172,19 +180,21 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
<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
<application>postmaster</application> is running. If host begins
with a slash, it is used as the directory for the unix domain
with a slash, it is used as the directory for the Unix- domain
socket.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-H, --html</term>
<term><option>-H</></term>
<term><option>--html</></term>
<listitem>
<para>
Turns on <acronym>HTML</acronym> tabular output. This is
@ -195,7 +205,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-l, --list</term>
<term><option>-l</></term>
<term><option>--list</></term>
<listitem>
<para>
Lists all available databases, then exits. Other non-connection
@ -206,7 +217,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-o, --output <replaceable class="parameter">filename</replaceable></term>
<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
@ -217,7 +229,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-p, --port <replaceable class="parameter">port</replaceable></term>
<term><option>-p <replaceable class="parameter">port</replaceable></></term>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
Specifies the TCP/IP port or, by omission, the local Unix domain
@ -231,7 +244,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
<term><option>-P <replaceable class="parameter">assignment</replaceable></></term>
<term><option>--pset <replaceable class="parameter">assignment</replaceable></></term>
<listitem>
<para>
Allows you to specify printing options in the style of
@ -244,7 +258,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-q</term>
<term><option>-q</></term>
<term><option>--quiet</></term>
<listitem>
<para>
Specifies that <application>psql</application> should do its work
@ -252,13 +267,14 @@ PostgreSQL documentation
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
<en var>QUIET</en var> variable to achieve the same effect.
<varname >QUIET</varname > variable to achieve the same effect.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
<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
@ -269,7 +285,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-s, --single-step</term>
<term><option>-s</></term>
<term><option>--single-step</></term>
<listitem>
<para>
Run in single-step mode. That means the user is prompted before
@ -280,7 +297,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-S, --single-line</term>
<term><option>-S</></term>
<term><option>--single-line</></term>
<listitem>
<para>
Runs in single-line mode where a newline terminates a query, as a
@ -299,7 +317,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-t, --tuples-only</term>
<term><option>-t</></term>
<term><option>--tuples-only</></term>
<listitem>
<para>
Turn off printing of column names and result row count footers,
@ -310,7 +329,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
<term><option>-T <replaceable class="parameter">table_options</replaceable></></term>
<term><option>--table-attr <replaceable class="parameter">table_options</replaceable></></term>
<listitem>
<para>
Allows you to specify options to be placed within the
@ -321,7 +341,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-u</term>
<term><option> -u</> </term>
<listitem>
<para>
Makes <application>psql</application> prompt for the user name and
@ -339,7 +359,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<term><option>-U <replaceable class="parameter">username</replaceable></></term>
<term><option>--username <replaceable class="parameter">username</replaceable></></term>
<listitem>
<para>
Connects to the database as the user <replaceable
@ -350,7 +371,9 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
<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>
Performs a variable assignment, like the <command>\set</command>
@ -365,7 +388,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-V, --version</term>
<term><option>-V</></term>
<term><option>--version</></term>
<listitem>
<para>
Shows the <application>psql</application> version.
@ -374,7 +398,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-W, --password</term>
<term><option>-W</></term>
<term><option>--password</></term>
<listitem>
<para>
Requests that <application>psql</application> should prompt for a
@ -396,7 +421,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-x, --expanded</term>
<term><option>-x</></term>
<term><option>--expanded</></term>
<listitem>
<para>
Turns on extended row format mode. This is equivalent to the
@ -406,7 +432,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-X, --no-psqlrc</term>
<term><option>-X,</></term>
<term><option>--no-psqlrc</></term>
<listitem>
<para>
Do not read the start-up file <filename>~/.psqlrc</filename>.
@ -415,7 +442,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term>-?, --help</term>
<term><option>-?</></term>
<term><option>--help</></term>
<listitem>
<para>
Shows help about <application>psql</application> command line
@ -435,7 +463,7 @@ PostgreSQL documentation
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 <en var>ON_ERROR_STOP</en var> was set.
script and the variable <varname >ON_ERROR_STOP</varname > was set.
</para>
</refsect1>
@ -458,7 +486,7 @@ PostgreSQL documentation
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
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.
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
@ -556,11 +584,11 @@ testdb=>
</para>
<para>
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 backtick s.
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
backquote s.
</para>
<para>
@ -665,13 +693,13 @@ testdb=>
</varlistentry>
<varlistentry>
<term><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
<term><literal>\copy <replaceable class="parameter">table</replaceable>
{ <literal>from</literal> | <literal>to</literal> }
<replaceable class="parameter">filename</replaceable> | stdin | stdout
[ <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>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ]</literal>
</term>
<listitem>
@ -838,7 +866,7 @@ testdb=>
<note>
<para>
To reduce clutter, <literal>\df</> does not show datatype I/O
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>
@ -1087,7 +1115,7 @@ Tue Oct 26 21:40:57 CEST 1999
<note>
<para>
If you want to see the lines on the screen as they are read you
must set the variable <en var>ECHO</en var> to
must set the variable <varname >ECHO</varname > to
<literal>all</literal>.
</para>
</note>
@ -1132,7 +1160,7 @@ Tue Oct 26 21:40:57 CEST 1999
</tip>
<note>
<para>
See the description of the <en var>LO_TRANSACTION</en var>
See the description of the <varname >LO_TRANSACTION</varname >
variable for important information concerning all large object
operations.
</para>
@ -1169,7 +1197,7 @@ lo_import 152801
<note>
<para>
See the description of the <en var>LO_TRANSACTION</en var>
See the description of the <varname >LO_TRANSACTION</varname >
variable for important information concerning all large object
operations.
</para>
@ -1206,7 +1234,7 @@ lo_import 152801
</tip>
<note>
<para>
See the description of the <en var>LO_TRANSACTION</en var>
See the description of the <varname >LO_TRANSACTION</varname >
variable for important information concerning all large object
operations.
</para>
@ -1426,7 +1454,7 @@ lo_import 152801
<term><literal>pager</literal></term>
<listitem>
<para>
Toggles the use of a pager for query and psql help output. If the
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
<filename>more</filename>) is used.
@ -1775,7 +1803,7 @@ bar
such variables. A list of all specially treated variables follows.
<variablelist>
<varlistentry>
<term><en var>DBNAME</en var></term>
<term><varname >DBNAME</varname ></term>
<listitem>
<para>
The name of the database you are currently connected to. This is
@ -1786,7 +1814,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>ECHO</en var></term>
<term><varname >ECHO</varname ></term>
<listitem>
<para>
If set to <quote><literal>all</literal></quote>, all lines
@ -1802,14 +1830,14 @@ bar
</varlistentry>
<varlistentry>
<term><en var>ECHO_HIDDEN</en var></term>
<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. If you set the
variable to the value <quote>noexec</quote >, the queries are
variable to the value <literal>noexec</literal >, the queries are
just shown but are not actually sent to the backend and
executed.
</para>
@ -1817,7 +1845,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>ENCODING</en var></term>
<term><varname >ENCODING</varname ></term>
<listitem>
<para>
The current client multibyte encoding. If you are not set up to
@ -1828,7 +1856,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>HISTCONTROL</en var></term>
<term><varname >HISTCONTROL</varname ></term>
<listitem>
<para>
If this variable is set to <literal>ignorespace</literal>,
@ -1849,7 +1877,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>HISTSIZE</en var></term>
<term><varname >HISTSIZE</varname ></term>
<listitem>
<para>
The number of commands to store in the command history. The
@ -1865,7 +1893,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>HOST</en var></term>
<term><varname >HOST</varname ></term>
<listitem>
<para>
The database server host you are currently connected to. This is
@ -1876,15 +1904,16 @@ bar
</varlistentry>
<varlistentry>
<term><en var>IGNOREEOF</en var></term>
<term><varname >IGNOREEOF</varname ></term>
<listitem>
<para>
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.
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>
@ -1896,10 +1925,10 @@ bar
</varlistentry>
<varlistentry>
<term><en var>LASTOID</en var></term>
<term><varname >LASTOID</varname ></term>
<listitem>
<para>
The value of the last affected oid , as returned from an
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
@ -1909,7 +1938,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>LO_TRANSACTION</en var></term>
<term><varname >LO_TRANSACTION</varname ></term>
<listitem>
<para>
If you use the <productname>PostgreSQL</productname> large
@ -1943,7 +1972,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>ON_ERROR_STOP</en var></term>
<term><varname >ON_ERROR_STOP</varname ></term>
<listitem>
<para>
By default, if non-interactive scripts encounter an error, such
@ -1963,7 +1992,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>PORT</en var></term>
<term><varname >PORT</varname ></term>
<listitem>
<para>
The database server port to which you are currently connected.
@ -1974,7 +2003,9 @@ bar
</varlistentry>
<varlistentry>
<term><envar>PROMPT1</envar>, <envar>PROMPT2</envar>, <envar>PROMPT3</envar></term>
<term><varname>PROMPT1</varname></term>
<term><varname>PROMPT2</varname></term>
<term><varname>PROMPT3</varname></term>
<listitem>
<para>
These specify what the prompt <application>psql</application>
@ -1986,7 +2017,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>QUIET</en var></term>
<term><varname >QUIET</varname ></term>
<listitem>
<para>
This variable is equivalent to the command line option
@ -1997,7 +2028,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>SINGLELINE</en var></term>
<term><varname >SINGLELINE</varname ></term>
<listitem>
<para>
This variable is set by the command line option
@ -2007,7 +2038,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>SINGLESTEP</en var></term>
<term><varname >SINGLESTEP</varname ></term>
<listitem>
<para>
This variable is equivalent to the command line option
@ -2017,7 +2048,7 @@ bar
</varlistentry>
<varlistentry>
<term><en var>USER</en var></term>
<term><varname >USER</varname ></term>
<listitem>
<para>
The database user you are currently connected as. This is set
@ -2105,8 +2136,8 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<para>
The prompts <application>psql</application> issues can be customized
to your preference. The three variables <en var>PROMPT1</en var>,
<en var>PROMPT2</en var>, and <en var>PROMPT3</en var> contain strings
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 query. Prompt 2 is
@ -2251,11 +2282,11 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
</refsect3>
<refsect3>
<title>Readline </title>
<title>Command-Line Editing </title>
<para>
<application>psql</application> supports the readline and history
libraries for convenient line editing and retrieval. The command
<application>psql</application> supports the <application>Readline</application>
library 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
Peter Eisentraut
24 years ago