database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-11 20:28:21 +03:00
Code Activity

Fixed psql variables vs array syntax, as well as minor psql enhancements

Browse Source
This commit is contained in:
Peter Eisentraut
2000-01-14 22:18:03 +00:00
parent 4ceb2d0cb6
commit 7c9390caa1
21 changed files with 1009 additions and 922 deletions
Download Patch File Download Diff File Expand all files Collapse all files

554
doc/src/sgml/ref/psql-ref.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.19 2000/01/12 19:36:34 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.20 2000/01/14 22:18:01 petere Exp $
Postgres documentation
-->
@ -32,27 +32,20 @@ Postgres documentation
<date>1998-09-26</date>
</refsect2info>
<title>Input</title>
<title>Summary</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>PostgreSQL</productname>.
<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>
</refsect2>
<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>
</refsynopsisdiv>
<refsect1 id="R1-APP-PSQL-1">
@ -62,58 +55,31 @@ Postgres documentation
<title>Description</title>
<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">
<refsect2 id="R2-APP-PSQL-connecting">
<refsect2info>
<date>1998-09-26</date>
<date>2000-01-14</date>
</refsect2info>
<title>Connecting To A Database</title>
<para>
<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>,
<application>psql</application> is a regular <productname>PostgreSQL</productname>
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
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 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
local host. The default port number is compile-time determined. Since the database
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.
Note that you can't just connect to any database under any username. 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>, <envar>PGUSER</envar>,
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.)
respectively to appropriate values.
</para>
<para>
@ -151,8 +117,9 @@ testdb=>
<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. If the database server reports success, the query
results are displayed on the screen.
semicolon is reached. An end of line does not terminate a query! Thus queries
can be spread over serveral lines for clarity. If the query was sent and without
error the query results are displayed on the screen.
</para>
<para>
@ -173,12 +140,11 @@ testdb=>
<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). For this reason,
<application>psql</application> meta-commands are more commonly called
slash or backslash commands.
unquoted backslash is a <application>psql</application> meta-command that is
processes 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.
</para>
<para>
@ -268,11 +234,8 @@ testdb=>
</para>
<para>
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.
If <replaceable class="parameter">username</replaceable> is omitted
the current user name is assumed.
</para>
<para>
@ -293,10 +256,11 @@ testdb=>
</varlistentry>
<varlistentry>
<term><literal>\copy</literal> [ <literal>binary</literal> ] <replaceable class="parameter">table</replaceable>
<term><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
[ <literal>with oids</literal> ] { <literal>from</literal> | <literal>to</literal> }
<replaceable class="parameter">filename</replaceable> [ <literal>with delimiters</literal>
'<replaceable class="parameter">character</replaceable>' ]
<replaceable class="parameter">filename</replaceable> | stdin | stdout
[ <literal>with delimiters</literal> '<replaceable class="parameter">characters</replaceable>' ]
[ <literal>with null as</literal> '<replaceable class="parameter">string</replaceable>' ]
</term>
<listitem>
@ -326,6 +290,18 @@ testdb=>
technique may be preferable.
</para>
</tip>
<note>
<para>
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 whereever the <command>COPY</command>
itself came from (for example, a script ran with the <option>-f</option>) option,
and <literal>stdout</literal> refers to the query output stream (see
<command>\o</command> meta-command below).
</para>
</note>
</listitem>
</varlistentry>
@ -666,7 +642,7 @@ Tue Oct 26 21:40:57 CEST 1999
</tip>
<note>
<para>
See the description of the <envar>lo_transaction</envar> variable for
See the description of the <envar>LO_TRANSACTION</envar> variable for
important information concerning all large object operations.
</para>
</note>
@ -689,7 +665,7 @@ lo_import 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.
<command>\lo_list</command> command.
</para>
<para>
@ -700,7 +676,7 @@ lo_import 152801
<note>
<para>
See the description of the <envar>lo_transaction</envar> variable for
See the description of the <envar>LO_TRANSACTION</envar> variable for
important information concerning all large object operations.
</para>
</note>
@ -733,7 +709,7 @@ lo_import 152801
</tip>
<note>
<para>
See the description of the <envar>lo_transaction</envar> variable for
See the description of the <envar>LO_TRANSACTION</envar> variable for
important information concerning all large object operations.
</para>
</note>
@ -755,9 +731,11 @@ lo_import 152801
</para>
<para>
<quote>Query results</quote> includes all tables and notices obtained
<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>).
commands that query the database (such as <command>\d</command>),
but not error messages.
</para>
<tip>
@ -922,7 +900,7 @@ lo_import 152801
<para>
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>/bin/more</filename> is assumed.
Otherwise <filename>more</filename> is used.
</para>
<para>
@ -1024,10 +1002,8 @@ lo_import 152801
<para>
Sets the internal variable <replaceable class="parameter">name</replaceable>
to <replaceable class="parameter">value</replaceable>. If no second argument
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.
is given, the variable is just set with not value. To unset a variable, use
the <command>\unset</command> command.
</para>
<para>
@ -1192,14 +1168,7 @@ Access permissions for database "test"
<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, 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.
are not available on all systems.
</para>
<para>
@ -1221,8 +1190,7 @@ Access permissions for database "test"
<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.
and then exit. This is useful for shell scripts.
</para>
<para>
<replaceable class="parameter">query</replaceable> must be either a query string
@ -1254,20 +1222,20 @@ Access permissions for database "test"
<listitem>
<para>
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>.
This is equivalent to setting the variable <envar>ECHO</envar> to <literal>full</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-E, --echo-all</term>
<term>-E, --echo-hidden</term>
<listitem>
<para>
Echos 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_secret</envar> from within <application>psql</application>.
<envar>ECHO_HIDDEN</envar> from within <application>psql</application>.
</para>
</listitem>
</varlistentry>
@ -1337,7 +1305,7 @@ Access permissions for database "test"
<term>-n, --no-readline</term>
<listitem>
<para>
Do not use the readline library for input line editing and command history.
Do not use readline for line editing and do not use the history.
</para>
</listitem>
</varlistentry>
@ -1389,7 +1357,7 @@ Access permissions for database "test"
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.
also set the <envar>QUIET</envar> variable to achieve the same effect.
</para>
</listitem>
</varlistentry>
@ -1411,7 +1379,7 @@ Access permissions for database "test"
<term>-S, --single-line</term>
<listitem>
<para>
Runs in single-line mode where a newline sends a query, in addition to a semicolon.
Runs in single-line mode where a newline terminates a query, like a semicolon would do.
</para>
<note>
@ -1419,8 +1387,7 @@ Access permissions for database "test"
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 unexperienced user. Moral: Unless you exclusively type short queries,
avoid using this mode.
the unexperienced user.
</para>
</note>
</listitem>
@ -1472,9 +1439,7 @@ Access permissions for database "test"
<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.) If
<replaceable class="parameter">username</replaceable> is <quote>?</quote>, <application>psql</application>
issues an interactive prompt for the user name.
instead of the default. (You must have permission to do so, of course.)
</para>
</listitem>
</varlistentry>
@ -1486,7 +1451,9 @@ Access permissions for database "test"
<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.
line. To unset a variable, leave off the equal sign. These assignments are done
during a very early state of startup, so variables reserved for internal purposes
might get overwritten again.
</para>
</listitem>
</varlistentry>
@ -1503,7 +1470,7 @@ Access permissions for database "test"
<varlistentry>
<term>-W</term>
<term>-W, --password</term>
<listitem>
<para>
Requests that <application>psql</application> should prompt for a password
@ -1518,22 +1485,14 @@ Access permissions for database "test"
Because this is currently based on a <quote>hack</quote> 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 content of the environment variable <envar>PGPASSWORD</envar> is
taken. If this is not set, the connection attempt will fail.
the connection attempt will fail.
</para>
<caution>
<para>
If you are considering setting the variable <envar>PGPASSWORD</envar> to do
authentication, you have a problem.
</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term>-x</term>
<term>-x, --expanded</term>
<listitem>
<para>
Turns on extended row format mode. This is equivalent to the command
@ -1542,15 +1501,19 @@ Access permissions for database "test"
</listitem>
</varlistentry>
<varlistentry>
<term>-?, --help</term>
<listitem>
<para>
Shows help about <application>psql</application> command line arguments.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<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>
</refsect1>
@ -1585,7 +1548,7 @@ bar
testdb=> <userinput>\echo "foo is now ${foo}."</userinput>
foo is now bar.
</programlisting>
(The curly braces are required. This is not <productname>Perl</productname>.) No variable substitution
(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>).
</para>
@ -1604,76 +1567,52 @@ foo is now bar.
</para>
</note>
<para>
If you call <command>\set</command> without an argument, the variable is simply
set, but has no 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.
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.
</para>
<para>
A number of regular variables are treated specially by <application>psql</application>.
They indicate certain option settings that can be changed at runtime
by altering the value of the variable. Although you can use these
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. 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.
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.
<variablelist>
<varlistentry>
<term><envar>die_on_error</envar></term>
<term><envar>DBNAME</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 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).
The name of the database you are currently connected to. This is set everytime
you connect to a database (including program startup), but can be unset.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>echo</envar></term>
<term><envar>ECHO</envar></term>
<listitem>
<para>
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
If set to <quote><literal>full</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 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>echo_secret</envar></term>
<term><envar>ECHO_HIDDEN</envar></term>
<listitem>
<para>
When this variable is set and a backslash command queries the database, the query
@ -1686,7 +1625,98 @@ foo is now bar.
</varlistentry>
<varlistentry>
<term><envar>lo_transaction</envar></term>
<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>
<term><envar>HISTCONTROL</envar></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><envar>HISTSIZE</envar></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><envar>HOST</envar></term>
<listitem>
<para>
The database server host you are currently connected to. This is set everytime
you connect to a database (including program startup), but can be unset.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>IGNOREEOF</envar></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.
</para>
<note>
<para>
This feature was shamelessly plagiarized from <application>bash</application>.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>LASTOID</envar></term>
<listitem>
<para>
The value of the last affected oid, as returned from an <command>INSERT</command>
or <command>lo_insert</command> commmand. 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>
<term><envar>LO_TRANSACTION</envar></term>
<listitem>
<para>
If you use the <productname>PostgreSQL</productname> large object
@ -1702,7 +1732,7 @@ foo is now bar.
all. In the latter case you must provide you own
<command>BEGIN TRANSACTION</command>/<command>COMMIT</command> block or
the results will be unpredictable (usually resulting in the desired
action not being performed anyway).
action not being performed in any case).
</para>
<para>
@ -1717,7 +1747,17 @@ foo is now bar.
</varlistentry>
<varlistentry>
<term><envar>prompt1</envar>, <envar>prompt2</envar>, <envar>prompt3</envar></term>
<term><envar>PORT</envar></term>
<listitem>
<para>
The database server port you are currently connected to. This is set everytime
you connect to a database (including program startup), but can be unset.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>PROMPT1</envar>, <envar>PROMPT2</envar>, <envar>PROMPT3</envar></term>
<listitem>
<para>
These specify what the prompt <application>psql</application> issues is
@ -1729,7 +1769,7 @@ foo is now bar.
</varlistentry>
<varlistentry>
<term><envar>quiet</envar></term>
<term><envar>QUIET</envar></term>
<listitem>
<para>
This variable is equivalent to the command line option <option>-q</option>.
@ -1739,7 +1779,7 @@ foo is now bar.
</varlistentry>
<varlistentry>
<term><envar>singleline</envar></term>
<term><envar>SINGLELINE</envar></term>
<listitem>
<para>
This variable is set be the command line options <option>-S</option>. You
@ -1749,13 +1789,24 @@ foo is now bar.
</varlistentry>
<varlistentry>
<term><envar>singlestep</envar></term>
<term><envar>SINGLESTEP</envar></term>
<listitem>
<para>
This variable is equivalent to the command line option <option>-s</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>USER</envar></term>
<listitem>
<para>
The database user you are currently connected as. This is set everytime
you connect to a database (including program startup), but can be unset.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
@ -1814,6 +1865,15 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp
be better off preparing the file externally.
</para>
<para>
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.)
</para>
</refsect2>
@ -1822,8 +1882,8 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp
<para>
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
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
@ -1924,8 +1984,75 @@ testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinp
and 2, and <literal>'&gt;&gt; '</literal> for prompt 3.
</para>
<note>
<para>
This feature was shamelessly plagiarized from <application>tcsh</application>.
</para>
</note>
</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>EXIT_ON_ERROR</envar> was
set.
</para>
<para>
Before starting up in interactive mode, <application>psql</application> attempts
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).
</para>
</refsect2>
<refsect2>
<title><acronym>GNU</acronym> readline</title>
<para>
<application>psql</application> supports the readline and history libraries for
convenienent line editing and retrieval. The command history is stored in a file
named <filename>.psqlrc</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.
</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>
</refsect2>
</refsect1>
@ -2074,23 +2201,9 @@ Field separator is "oo".
<listitem>
<para>
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.
<application>psql</application> only works smootly 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>
@ -2098,7 +2211,7 @@ Field separator is "oo".
<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 (see previous item). Not that there is any command
to fixing this one day. Not that there is any command
that actually uses that many options though.
</para>
</listitem>
@ -2106,41 +2219,6 @@ Field separator is "oo".
</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>
</refsect2>
</refsect1>
</refentry>