database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-12-19 17:02:53 +03:00
Code Activity

Another big editing pass for consistent content and presentation.

Browse Source
This commit is contained in:
Peter Eisentraut
2003-03-24 14:32:51 +00:00
parent e27334f405
commit d258ba01ec
38 changed files with 1321 additions and 2427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
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.85 2003/02/13 05:37:43 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -20,9 +20,9 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>psql</command>
<arg><replaceable class="parameter">options</replaceable></arg>
<arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
<arg><replaceable class="parameter">dbname</replaceable>
<arg><replaceable class="parameter">user</replaceable></arg></arg>
<arg><replaceable class="parameter">username</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -69,17 +69,17 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term><option>-c <replaceable class="parameter">query</replaceable></></term>
<term><option>--command <replaceable class="parameter">query</replaceable></></term>
<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
query string, <replaceable class="parameter">query</replaceable>,
command string, <replaceable class="parameter">command</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 parsable by the backend (i.e.,
<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 it is a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application>
@@ -108,7 +108,7 @@ PostgreSQL documentation
<term><option>--echo-queries</></term>
<listitem>
<para>
Show all queries that are sent to the backend. This is equivalent
Show all commands that are sent to the server. This is equivalent
to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>.
</para>
@@ -120,7 +120,7 @@ PostgreSQL documentation
<term><option>--echo-hidden</></term>
<listitem>
<para>
Echoes the actual queries generated by \d and other backslash
Echo the actual queries generated by <command>\d</command> 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 <varname>ECHO_HIDDEN</varname> from within
@@ -135,7 +135,7 @@ PostgreSQL documentation
<listitem>
<para>
Use the file <replaceable class="parameter">filename</replaceable>
as the source of queries instead of reading queries interactively.
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>.
@@ -179,7 +179,7 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the host name of the machine on which the
<application>postmaster</application> is running. If host begins
server is running. If the value begins
with a slash, it is used as the directory for the Unix-domain
socket.
</para>
@@ -191,7 +191,7 @@ PostgreSQL documentation
<term><option>--html</></term>
<listitem>
<para>
Turns on <acronym>HTML</acronym> tabular output. This is
Turn on <acronym>HTML</acronym> tabular output. This is
equivalent to <literal>\pset format html</literal> or the
<command>\H</command> command.
</para>
@@ -203,7 +203,7 @@ PostgreSQL documentation
<term><option>--list</></term>
<listitem>
<para>
Lists all available databases, then exits. Other non-connection
List all available databases, then exits. Other non-connection
options are ignored. This is similar to the internal command
<command>\list</command>.
</para>
@@ -227,9 +227,8 @@ PostgreSQL documentation
<term><option>--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
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.
@@ -284,7 +283,7 @@ PostgreSQL documentation
<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
each command is sent to the server, with the option to cancel
execution as well. Use this to debug scripts.
</para>
</listitem>
@@ -295,7 +294,7 @@ PostgreSQL documentation
<term><option>--single-line</></term>
<listitem>
<para>
Runs in single-line mode where a newline terminates a query, as a
Runs in single-line mode where a newline terminates an SQL command, as a
semicolon does.
</para>
@@ -345,7 +344,7 @@ PostgreSQL documentation
<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
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>
@@ -357,7 +356,7 @@ PostgreSQL documentation
<term><option>--username <replaceable class="parameter">username</replaceable></></term>
<listitem>
<para>
Connects to the database as the user <replaceable
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>
@@ -370,7 +369,7 @@ PostgreSQL documentation
<term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
<listitem>
<para>
Performs a variable assignment, like the <command>\set</command>
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,
@@ -386,7 +385,7 @@ PostgreSQL documentation
<term><option>--version</></term>
<listitem>
<para>
Shows the <application>psql</application> version.
Show the <application>psql</application> version.
</para>
</listitem>
</varlistentry>
@@ -404,11 +403,11 @@ PostgreSQL documentation
<para>
In the current version, <application>psql</application>
automatically issues a password prompt whenever the backend
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 backend requires password authentication the
issued and the server requires password authentication the
connection attempt will fail.
</para>
</listitem>
@@ -419,7 +418,7 @@ PostgreSQL documentation
<term><option>--expanded</></term>
<listitem>
<para>
Turns on extended row format mode. This is equivalent to the
Turn on the extended table formatting mode. This is equivalent to the
command <command>\x</command>.
</para>
</listitem>
@@ -440,7 +439,7 @@ PostgreSQL documentation
<term><option>--help</></term>
<listitem>
<para>
Shows help about <application>psql</application> command line
Show help about <application>psql</application> command line
arguments.
</para>
</listitem>
@@ -455,8 +454,8 @@ PostgreSQL documentation
<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
file not found) occurs, 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>
@@ -495,13 +494,13 @@ PostgreSQL documentation
<para>
If the connection could not be made for any reason (e.g., insufficient
privileges, postmaster is not running on the server, etc.),
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 Queries</title>
<title>Entering SQL Commands</title>
<para>
In normal operation, <application>psql</application> provides a
@@ -523,16 +522,16 @@ testdb=>
</para>
<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
At the prompt, the user may 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 without error, the results of the command
are displayed on the screen.
</para>
<para>
Whenever a query is executed, <application>psql</application> also polls
Whenever a command 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">.
@@ -586,18 +585,23 @@ testdb=>
</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> regarding double quotes: an
identifier without double quotes is coerced to lower-case, while
whitespace within double quotes is included in the argument.
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 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
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
@@ -612,8 +616,8 @@ testdb=>
<term><literal>\a</literal></term>
<listitem>
<para>
If the current table output format is unaligned, switch to aligned.
If it is not unaligned, set it to unaligned. This command is
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.
</para>
@@ -624,8 +628,8 @@ testdb=>
<term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
<listitem>
<para>
Change the current working directory to
<replaceable>directory</replaceable>. Without argument, change
Changes the current working directory to
<replaceable>directory</replaceable>. Without argument, changes
to the current user's home directory.
</para>
@@ -641,7 +645,7 @@ testdb=>
<term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
<listitem>
<para>
Set the title of any tables being printed as the result of a
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
@@ -701,10 +705,10 @@ testdb=>
<para>
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
endterm="SQL-COPY-title"> 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 backend and the local file system.
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.
@@ -712,8 +716,8 @@ testdb=>
<para>
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,
<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.
@@ -723,7 +727,7 @@ testdb=>
<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
through the client/server connection. For large
amounts of data the other technique may be preferable.
</para>
</tip>
@@ -732,9 +736,9 @@ testdb=>
<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
client and server copies: in a client copy these always
refer to <application>psql</application>'s input and output
stream. On a backend copy <literal>stdin</literal> comes from
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
<literal>stdout</literal> refers to the query output stream (see
@@ -792,7 +796,7 @@ testdb=>
<para>
Lists all available aggregate functions, together with the data
type they operate on. If <replaceable
class="parameter">pattern</replaceable> (a regular expression)
class="parameter">pattern</replaceable>
is specified, only matching aggregates are shown.
</para>
</listitem>
@@ -845,16 +849,8 @@ testdb=>
<para>
Descriptions for objects can be created with the
<command>COMMENT ON</command> <acronym>SQL</acronym> command.
<command>COMMENT</command> <acronym>SQL</acronym> command.
</para>
<note>
<para>
<productname>PostgreSQL</productname> stores the object
descriptions in the <structname>pg_description</> system table.
</para>
</note>
</listitem>
</varlistentry>
@@ -863,7 +859,7 @@ testdb=>
<term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
<listitem>
<para>
Lists all available domains (derived types). If <replaceable
Lists all available domains. If <replaceable
class="parameter">pattern</replaceable>
is specified, only matching domains are shown.
</para>
@@ -907,12 +903,12 @@ testdb=>
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 <quote>+</quote> is appended to the command name, each object is
If <literal>+</literal> is appended to the command name, each object is
listed with its associated description, if any.
</para>
<para>
If a <replaceable class="parameter">pattern</replaceable> is
If <replaceable class="parameter">pattern</replaceable> is
specified, only objects whose name matches the pattern are listed.
</para>
</listitem>
@@ -948,7 +944,7 @@ testdb=>
<listitem>
<para>
Lists available operators with their operand and return types.
If a <replaceable class="parameter">pattern</replaceable> is
If <replaceable class="parameter">pattern</replaceable> is
specified, only operators whose name matches the pattern are listed.
</para>
</listitem>
@@ -960,15 +956,15 @@ testdb=>
<listitem>
<para>
Produces a list of all available tables with their
associated access permissions.
If a <replaceable class="parameter">pattern</replaceable> is
associated access privileges.
If <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed.
</para>
<para>
The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE">
are used to set access permissions. See <xref linkend="SQL-GRANT">
are used to set access privileges. See <xref linkend="SQL-GRANT">
for more information.
</para>
</listitem>
@@ -991,7 +987,7 @@ testdb=>
<term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
Lists all database users, or only those that match <replaceable
Lists all database users or only those that match <replaceable
class="parameter">pattern</replaceable>.
</para>
</listitem>
@@ -1063,13 +1059,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Sets the client encoding. Without an argument, this command
Sets the client character set encoding. Without an argument, this command
shows the current encoding.
</para>
<note>
<para>
This command will not notice changes made directly by <command>SET
CLIENT_ENCODING</>. If you use <literal>\encoding</literal>,
client_encoding</>. If you use <command>\encoding</command>,
be sure to use it to set as well as examine the encoding.
</para>
</note>
@@ -1083,7 +1079,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Sets the field separator for unaligned query output. The default
is pipe (<literal>|</literal>). See also
is the vertical bar (<literal>|</literal>). See also
<command>\pset</command> for a generic way of setting output
options.
</para>
@@ -1096,7 +1092,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Sends the current query input buffer to the backend and
Sends the current query input buffer to the server and
optionally saves the output in <replaceable
class="parameter">filename</replaceable> or pipes the output
into a separate Unix shell to execute <replaceable
@@ -1112,12 +1108,12 @@ Tue Oct 26 21:40:57 CEST 1999
<term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
<listitem>
<para>
Give syntax help on the specified <acronym>SQL</acronym>
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 (<quote>*</quote>), then syntax help on all
asterisk (<literal>*</literal>), then syntax help on all
<acronym>SQL</acronym> commands is shown.
</para>
@@ -1169,8 +1165,8 @@ Tue Oct 26 21:40:57 CEST 1999
<term><literal>\l</literal> (or <literal>\list</literal>)</term>
<listitem>
<para>
List the names, owners, and encodings of all the databases in
the server. Append a <quote>+</quote> to the command name to
List the names, owners, and character set encodings of all the databases in
the server. Append a <literal>+</literal> to the command name to
see any descriptions for the databases as well.
</para>
</listitem>
@@ -1214,13 +1210,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Stores the file into a <productname>PostgreSQL</productname>
<quote>large object</quote>. Optionally, it associates the given
large object. Optionally, it associates the given
comment with the object. Example:
<programlisting>
foo=> <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
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
@@ -1249,7 +1245,7 @@ lo_import 152801
<listitem>
<para>
Shows a list of all <productname>PostgreSQL</productname>
<quote>large objects</quote> currently stored in the database,
large objects currently stored in the database,
along with any comments provided for them.
</para>
</listitem>
@@ -1291,8 +1287,7 @@ lo_import 152801
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
<filename>stdout</filename>.
specified, the query output will be reset to the standard output.
</para>
<para>
@@ -1349,7 +1344,7 @@ lo_import 152801
</para>
<para>
<quote>Unaligned</quote> writes all fields of a tuple on a
<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).
@@ -1385,14 +1380,14 @@ lo_import 152801
<listitem>
<para>
Toggles between regular and expanded format. When expanded
format is enabled, all output has two columns with the field
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 modes.
Expanded mode is supported by all four output formats.
</para>
</listitem>
</varlistentry>
@@ -1402,7 +1397,7 @@ lo_import 152801
<listitem>
<para>
The second argument is a string that should be printed
whenever a field is null. The default is not to print
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>.
@@ -1419,7 +1414,7 @@ lo_import 152801
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 <quote>pipe</quote> symbol).
<literal>'|'</literal> (a vertical bar).
</para>
</listitem>
</varlistentry>
@@ -1464,13 +1459,6 @@ lo_import 152801
can be used to give your output descriptive tags. If no
argument is given, the title is unset.
</para>
<note>
<para>
This formerly only affected <acronym>HTML</acronym> mode. You
can now set titles in any output format.
</para>
</note>
</listitem>
</varlistentry>
@@ -1512,6 +1500,9 @@ lo_import 152801
</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.
@@ -1541,7 +1532,7 @@ lo_import 152801
<term><literal>\q</literal></term>
<listitem>
<para>
Quit the <application>psql</application> program.
Quits the <application>psql</application> program.
</para>
</listitem>
</varlistentry>
@@ -1608,8 +1599,9 @@ lo_import 152801
<para>
Valid variable names can contain characters, digits, and
underscores. See the section about
<application>psql</application> variables for details.
underscores. See the section <xref
linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title"> below for details.
</para>
<para>
@@ -1644,7 +1636,7 @@ lo_import 152801
<term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
<listitem>
<para>
Allows you to specify options to be placed within the
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
tableattr <replaceable
@@ -1680,7 +1672,7 @@ lo_import 152801
<term><literal>\x</literal></term>
<listitem>
<para>
Toggles extended row format mode. As such it is equivalent to
Toggles extended table formatting mode. As such it is equivalent to
<literal>\pset expanded</literal>.
</para>
</listitem>
@@ -1692,7 +1684,7 @@ lo_import 152801
<listitem>
<para>
Produces a list of all available tables with their
associated access permissions.
associated access privileges.
If a <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed.
</para>
@@ -1700,13 +1692,13 @@ lo_import 152801
<para>
The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE">
are used to set access permissions. See <xref linkend="SQL-GRANT">
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
permissions</quote>).
privileges</quote>).
</para>
</listitem>
</varlistentry>
@@ -1729,8 +1721,7 @@ lo_import 152801
<term><literal>\?</literal></term>
<listitem>
<para>
Get help information about the backslash (<quote>\</quote>)
commands.
Shows help information about the backslash commands.
</para>
</listitem>
</varlistentry>
@@ -1741,31 +1732,20 @@ lo_import 152801
<para>
The various <literal>\d</> commands accept a <replaceable
class="parameter">pattern</replaceable> parameter to specify the
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
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.
</para>
<para>
A pattern that contains an (unquoted) dot is interpreted as a schema
name pattern followed by an object name pattern. For example,
<literal> \dt foo*.bar*</> displays all tables in schemas whose name
<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
matches only objects that are visible in the current schema search path.
@@ -1787,17 +1767,16 @@ lo_import 152801
<para>
<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
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=> <userinput>\set foo bar</userinput>
</programlisting>
sets the variable <quote>foo</quote> to the value
<quote>bar</quote>. To retrieve the content of the variable, precede
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>
@@ -1840,6 +1819,8 @@ bar
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.
</para>
<variablelist>
<varlistentry>
<term><varname>DBNAME</varname></term>
@@ -1856,13 +1837,13 @@ bar
<term><varname>ECHO</varname></term>
<listitem>
<para>
If set to <quote><literal>all</literal></quote>, all lines
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 specify this on program
start-up, use the switch <option>-a</option>. If set to
<quote><literal>queries</literal></quote>,
<literal>queries</literal>,
<application>psql</application> merely prints all queries as
they are sent to the backend. The option for this is
they are sent to the server. The option for this is
<option>-e</option>.
</para>
</listitem>
@@ -1877,7 +1858,7 @@ bar
<productname>PostgreSQL</productname> internals and provide
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 backend and
just shown but are not actually sent to the server and
executed.
</para>
</listitem>
@@ -1887,9 +1868,7 @@ bar
<term><varname>ENCODING</varname></term>
<listitem>
<para>
The current client multibyte encoding. If you are not set up to
use multibyte characters, this variable will always contain
<quote>SQL_ASCII</quote>.
The current client character set encoding.
</para>
</listitem>
</varlistentry>
@@ -1909,7 +1888,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
<application>bash</application>.
<application>Bash</application>.
</para>
</note>
</listitem>
@@ -1925,7 +1904,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
<application>bash</application>.
<application>Bash</application>.
</para>
</note>
</listitem>
@@ -1957,7 +1936,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
<application>bash</application>.
<application>Bash</application>.
</para>
</note>
</listitem>
@@ -1982,7 +1961,7 @@ bar
<para>
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
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
@@ -1992,16 +1971,15 @@ bar
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
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
<quote>rollback</quote>, <quote>commit</quote>, or
<quote>nothing</quote>. The default is to roll back the
<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
@@ -2015,7 +1993,7 @@ bar
<listitem>
<para>
By default, if non-interactive scripts encounter an error, such
as a malformed <acronym>SQL</acronym> query or internal
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
@@ -2048,9 +2026,9 @@ bar
<listitem>
<para>
These specify what the prompt <application>psql</application>
issues is supposed to look like. See <quote><xref
issues is supposed to look like. See <xref
linkend="APP-PSQL-prompting"
endterm="APP-PSQL-prompting-title"></quote> below.
endterm="APP-PSQL-prompting-title"> below.
</para>
</listitem>
</varlistentry>
@@ -2099,8 +2077,6 @@ bar
</variablelist>
</para>
</refsect3>
<refsect3>
@@ -2127,7 +2103,7 @@ testdb=> <userinput>SELECT * FROM :foo;</userinput>
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
copy the contents of a file into a table column. First load the file into a
variable and then proceed as above.
<programlisting>
testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
@@ -2135,8 +2111,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
</programlisting>
One possible 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 third line is processed. This
could be done with the program <application>sed</application>:
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=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
</programlisting>
@@ -2144,9 +2120,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
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
quotes and execute <command>sed</command> with the arguments
<literal>-e</literal> and <literal>s/'/\\'/g</literal>. When
<application>sed</application> parses this it will replace the two
<command>sed</command> 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
@@ -2157,12 +2133,12 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
</para>
<para>
Since colons may legally appear in queries, the following rule
Since colons may legally appear in SQL commands, 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>.
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.)
@@ -2179,17 +2155,17 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<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
issued when more input is expected during query input because the
query was not terminated with a semicolon or a quote was not closed.
<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
tuples on the terminal.
row values on the terminal.
</para>
<para>
The value of the respective prompt variable is printed literally,
except where a percent sign (<quote>%</quote>) is encountered.
except where a percent sign (<literal>%</literal>) is encountered.
Depending on the next character, certain other text is substituted
instead. Defined substitutions are:
@@ -2212,7 +2188,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<term><literal>%m</literal></term>
<listitem>
<para>
The host name of the database server, truncated after the
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>
@@ -2237,28 +2213,28 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<varlistentry>
<term><literal>%~</literal></term>
<listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
<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 current user is a database superuser, then a
<quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
<literal>#</literal>, otherwise a <literal>&gt;</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>%R</literal></term>
<listitem>
<para>
In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if
in single-line mode, and <quote>!</quote> if the session is
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 <quote>-</quote>, <quote>*</quote>, a single quote,
replaced by <literal>-</literal>, <literal>*</literal>, 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
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 resolve to anything.
</para>
@@ -2284,10 +2260,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
<listitem>
<para>
The value of the <application>psql</application>, variable
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.
section <xref linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title"> for details.
</para>
</listitem>
</varlistentry>
@@ -2330,9 +2306,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
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
<acronym>SQL</acronym> parser. 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:
<programlisting>
@@ -2341,7 +2315,7 @@ set disable-completion on
$endif
</programlisting>
(This is not a <application>psql</application> but a
<application>readline</application> feature. Read its documentation
<application>Readline</application> feature. Read its documentation
for further details.)
</para>
</refsect3>
@@ -2471,12 +2445,12 @@ $endif
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 I am not going to explain the details here as this use is
but were 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=> <userinput>\foo</userinput>
Field separator is "oo",
Field separator is "oo".
</programlisting>
which is perhaps not what one would expect.
</para>
@@ -2494,10 +2468,11 @@ Field separator is "oo",
<listitem>
<para>
Pressing Control-C during a <quote>copy in</quote> (data sent to
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 <quote>COPY state must be terminated
first</quote>, simply reset the connection by entering <literal>\c
message such as <errorname>COPY state must be terminated
first</errorname>, simply reset the connection by entering <literal>\c
- -</literal>.
</para>
</listitem>
@@ -2515,19 +2490,19 @@ Field separator is "oo",
<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.
&cite-tutorial;.
</para>
</note>
<para>
The first example shows how to spread a query over several lines of
The first example shows how to spread a command over several lines of
input. Notice the changing prompt:
<programlisting>
testdb=> <userinput>CREATE TABLE my_table (</userinput>
testdb(> <userinput> first integer not null default 0,</userinput>
testdb(> <userinput> second text</userinput>
testdb-> <userinput>);</userinput>
CREATE
CREATE TABLE
</programlisting>
Now look at the table definition again:
<programlisting>
@@ -2539,8 +2514,7 @@ testdb=> <userinput>\d my_table</userinput>
second | text |
</programlisting>
At this point you decide to change the prompt to something more
interesting:
Now we change the prompt to something more interesting:
<programlisting>
testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
peter@localhost testdb=>