<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.68 2002/07/15 01:56:25 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.69 2002/07/28 15:22:21 petere Exp $
PostgreSQL documentation
-->
<refentry id="APP-PSQL">
- <docinfo>
- <date>2000-12-25</date>
- </docinfo>
-
<refmeta>
<refentrytitle id="app-psql-title"><application>psql</application></refentrytitle>
<manvolnum>1</manvolnum>
</refpurpose>
</refnamediv>
- <refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>1999-10-26</date>
- </refsynopsisdivinfo>
-
- <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>psql</command>
+ <arg><replaceable class="parameter">options</replaceable></arg>
+ <arg><replaceable class="parameter">dbname</replaceable>
+ <arg><replaceable class="parameter">user</replaceable></arg></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
- <refsect2 id="R2-APP-PSQL-1">
- <refsect2info>
- <date>1998-09-26</date>
- </refsect2info>
-
- <title>Summary</title>
+ <refsect1>
+ <title>Description</title>
<para>
<application>psql</application> is a terminal-based front-end to
number of meta-commands and various shell-like features to
facilitate writing scripts and automating a wide variety of tasks.
</para>
+ </refsect1>
- </refsect2>
+ <refsect1 id="R1-APP-PSQL-3">
+ <title>Options</title>
-</refsynopsisdiv>
+ <para>
+ If so configured, <application>psql</application> understands both
+ standard Unix short options, and <acronym>GNU</acronym>-style long
+ options. The latter are not available on all systems.
+ </para>
-<refsect1 id="R1-APP-PSQL-1">
- <refsect1info>
- <date>1998-10-26</date>
- </refsect1info>
+ <variablelist>
+ <varlistentry>
+ <term>-a, --echo-all</term>
+ <listitem>
+ <para>
+ Print all the lines to the screen as they are read. This is more
+ useful for script processing rather than interactive mode. This is
+ equivalent to setting the variable <envar>ECHO</envar> to
+ <literal>all</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <title>Description</title>
+ <varlistentry>
+ <term>-A, --no-align</term>
+ <listitem>
+ <para>
+ Switches to unaligned output mode. (The default output mode is
+ otherwise aligned.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-c, --command <replaceable class="parameter">query</replaceable></term>
+ <listitem>
+ <para>
+ Specifies that <application>psql</application> is to execute one
+ query string, <replaceable class="parameter">query</replaceable>,
+ and then exit. This is useful in shell scripts.
+ </para>
+ <para>
+ <replaceable class="parameter">query</replaceable> must be either
+ a query string that is completely parseable by the backend (i.e.,
+ it contains no <application>psql</application> specific features),
+ or it is a single backslash command. Thus you cannot mix
+ <acronym>SQL</acronym> and <application>psql</application>
+ meta-commands. To achieve that, you could pipe the string into
+ <application>psql</application>, like this: <literal>echo "\x \\
+ select * from foo;" | psql</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <refsect2 id="R2-APP-PSQL-connecting">
- <refsect2info>
- <date>2000-01-14</date>
- </refsect2info>
-
- <title>Connecting To A Database</title>
+ <varlistentry>
+ <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the name of the database to connect to. This is
+ equivalent to specifying <replaceable
+ class="parameter">dbname</replaceable> as the first non-option
+ argument on the command line.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- <application>psql</application> is a regular
- <productname>PostgreSQL</productname> client application. In order
- to connect to a database you need to know the name of your target
- database, the host name and port number of the server and what user
- name you want to connect as. <application>psql</application> can be
- told about those parameters via command line options, namely
- <option>-d</option>, <option>-h</option>, <option>-p</option>, and
- <option>-U</option> respectively. If an argument is found that does
- not belong to any option it will be interpreted as the database name
- (or the user name, if the database name is also given). Not all
- these options are required, defaults do apply. If you omit the host
- name psql will connect via a Unix domain socket to a server on the
- local host. The default port number is compile-time determined.
- Since the database server uses the same default, you will not have
- to specify the port in most cases. The default user name is your
- Unix user name, as is the default database name. Note that you can't
- just connect to any database under any user name. Your database
- administrator should have informed you about your access rights. To
- save you some typing you can also set the environment variables
- <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
- <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
- values.
- </para>
+ <varlistentry>
+ <term>-e, --echo-queries</term>
+ <listitem>
+ <para>
+ Show all queries that are sent to the backend. This is equivalent
+ to setting the variable <envar>ECHO</envar> to
+ <literal>queries</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- If the connection could not be made for any reason (e.g., insufficient
- privileges, postmaster is not running on the server, etc.),
- <application>psql</application> will return an error and terminate.
- </para>
- </refsect2>
+ <varlistentry>
+ <term>-E, --echo-hidden</term>
+ <listitem>
+ <para>
+ Echoes the actual queries generated by \d and other backslash
+ commands. You can use this if you wish to include similar
+ functionality into your own programs. This is equivalent to
+ setting the variable <envar>ECHO_HIDDEN</envar> from within
+ <application>psql</application>.
+ </para>
+ </listitem>
+ </varlistentry>
- <refsect2 id="R2-APP-PSQL-4">
- <refsect2info>
- <date>1998-09-26</date>
- </refsect2info>
+ <varlistentry>
+ <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
+ <listitem>
+ <para>
+ Use the file <replaceable class="parameter">filename</replaceable>
+ as the source of queries instead of reading queries interactively.
+ After the file is processed, <application>psql</application>
+ terminates. This is in many ways equivalent to the internal
+ command <command>\i</command>.
+ </para>
- <title>Entering Queries</title>
+ <para>
+ If <replaceable>filename</replaceable> is <literal>-</literal>
+ (hyphen), then standard input is read.
+ </para>
- <para>
- In normal operation, <application>psql</application> provides a
- prompt with the name of the database to which
- <application>psql</application> is currently connected, followed by
- the string <literal>=></literal>. For example,
-<programlisting>
-$ <userinput>psql testdb</userinput>
-Welcome to psql, the PostgreSQL interactive terminal.
+ <para>
+ Using this option is subtly different from writing <literal>psql
+ < <replaceable
+ class="parameter">filename</replaceable></literal>. In general,
+ both will do what you expect, but using <literal>-f</literal>
+ enables some nice features such as error messages with line
+ numbers. There is also a slight chance that using this option will
+ reduce the start-up overhead. On the other hand, the variant using
+ the shell's input redirection is (in theory) guaranteed to yield
+ exactly the same output that you would have gotten had you entered
+ everything by hand.
+ </para>
+ </listitem>
+ </varlistentry>
-Type: \copyright for distribution terms
- \h for help with SQL commands
- \? for help on internal slash commands
- \g or terminate with semicolon to execute query
- \q to quit
+ <varlistentry>
+ <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
+ <listitem>
+ <para>
+ Use <replaceable class="parameter">separator</replaceable> as the
+ field separator. This is equivalent to <command>\pset
+ fieldsep</command> or <command>\f</command>.
+ </para>
+ </listitem>
+ </varlistentry>
-testdb=>
-</programlisting>
- </para>
+ <varlistentry>
+ <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the host name of the machine on which the
+ <application>postmaster</application> is running. If host begins
+ with a slash, it is used as the directory for the unix domain
+ socket.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- At the prompt, the user may type in <acronym>SQL</acronym> queries.
- Ordinarily, input lines are sent to the backend when a
- query-terminating semicolon is reached. An end of line does not
- terminate a query! Thus queries can be spread over several lines for
- clarity. If the query was sent and without error, the query results
- are displayed on the screen.
- </para>
+ <varlistentry>
+ <term>-H, --html</term>
+ <listitem>
+ <para>
+ Turns on <acronym>HTML</acronym> tabular output. This is
+ equivalent to <literal>\pset format html</literal> or the
+ <command>\H</command> command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-l, --list</term>
+ <listitem>
+ <para>
+ Lists all available databases, then exits. Other non-connection
+ options are ignored. This is similar to the internal command
+ <command>\list</command>.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- Whenever a query is executed, <application>psql</application> also polls
- for asynchronous notification events generated by
- <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
- <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
- </para>
- </refsect2>
-</refsect1>
+ <varlistentry>
+ <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
+ <listitem>
+ <para>
+ Put all query output into file <replaceable
+ class="parameter">filename</replaceable>. This is equivalent to
+ the command <command>\o</command>.
+ </para>
+ </listitem>
+ </varlistentry>
-<refsect1 id="R1-APP-PSQL-2">
- <refsect1info>
- <date>1998-09-26</date>
- </refsect1info>
+ <varlistentry>
+ <term>-p, --port <replaceable class="parameter">port</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the TCP/IP port or, by omission, the local Unix domain
+ socket file extension on which the
+ <application>postmaster</application> is listening for
+ connections. Defaults to the value of the <envar>PGPORT</envar>
+ environment variable or, if not set, to the port specified at
+ compile time, usually 5432.
+ </para>
+ </listitem>
+ </varlistentry>
- <title><application>psql</application> Meta-Commands</title>
+ <varlistentry>
+ <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
+ <listitem>
+ <para>
+ Allows you to specify printing options in the style of
+ <command>\pset</command> on the command line. Note that here you
+ have to separate name and value with an equal sign instead of a
+ space. Thus to set the output format to LaTeX, you could write
+ <literal>-P format=latex</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- Anything you enter in <application>psql</application> that begins
- with an unquoted backslash is a <application>psql</application>
- meta-command that is processed by <application>psql</application>
- itself. These commands are what makes
- <application>psql</application> interesting for administration or
- scripting. Meta-commands are more commonly called slash or backslash
- commands.
- </para>
-
- <para>
- The format of a <application>psql</application> command is the backslash,
- followed immediately by a command verb, then any arguments. The arguments
- are separated from the command verb and each other by any number of
- whitespace characters.
- </para>
-
- <para>
- To include whitespace into an argument you must quote it with a
- single quote. To include a single quote into such an argument,
- precede it by a backslash. Anything contained in single quotes is
- furthermore subject to C-like substitutions for
- <literal>\n</literal> (new line), <literal>\t</literal> (tab),
- <literal>\</literal><replaceable>digits</replaceable>,
- <literal>\0</literal><replaceable>digits</replaceable>, and
- <literal>\0x</literal><replaceable>digits</replaceable> (the
- character with the given decimal, octal, or hexadecimal code).
- </para>
-
- <para>
- If an unquoted argument begins with a colon (<literal>:</literal>),
- it is taken as a variable and the value of the variable is taken as
- the argument instead.
- </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 a trailing newline
- removed) is taken as the argument value. The above escape sequences
- also apply in backticks.
- </para>
-
- <para>
- Some commands take the name of an <acronym>SQL</acronym> identifier
- (such as a table name) as argument. These arguments follow the
- syntax rules of <acronym>SQL</acronym> regarding double quotes: an
- identifier without double quotes is coerced to lower-case. For all
- other commands double quotes are not special and will become part of
- the argument.
- </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
- any. That way <acronym>SQL</acronym> and
- <application>psql</application> commands can be freely mixed on a
- line. But in any case, the arguments of a meta-command cannot
- continue beyond the end of the line.
- </para>
-
- <para>
- The following meta-commands are defined:
+ <varlistentry>
+ <term>-q</term>
+ <listitem>
+ <para>
+ Specifies that <application>psql</application> should do its work
+ quietly. By default, it prints welcome messages and various
+ informational output. If this option is used, none of this
+ happens. This is useful with the <option>-c</option> option.
+ Within <application>psql</application> you can also set the
+ <envar>QUIET</envar> variable to achieve the same effect.
+ </para>
+ </listitem>
+ </varlistentry>
- <variablelist>
- <varlistentry>
- <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
- kept for backwards compatibility. See <command>\pset</command> for a
- general solution.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
+ <listitem>
+ <para>
+ Use <replaceable class="parameter">separator</replaceable> as the
+ record separator. This is equivalent to the <command>\pset
+ recordsep</command> command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-s, --single-step</term>
+ <listitem>
+ <para>
+ Run in single-step mode. That means the user is prompted before
+ each query is sent to the backend, with the option to cancel
+ execution as well. Use this to debug scripts.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
- <listitem>
- <para>
- Change the current working directory to
- <replaceable>directory</replaceable>. Without argument, change
- to the current user's home directory.
- </para>
+ <varlistentry>
+ <term>-S, --single-line</term>
+ <listitem>
+ <para>
+ Runs in single-line mode where a newline terminates a query, as a
+ semicolon does.
+ </para>
- <tip>
- <para>
- To print your current working directory, use <literal>\!pwd</literal>.
- </para>
- </tip>
- </listitem>
- </varlistentry>
+ <note>
+ <para>
+ This mode is provided for those who insist on it, but you are not
+ necessarily encouraged to use it. In particular, if you mix
+ <acronym>SQL</acronym> and meta-commands on a line the order of
+ execution might not always be clear to the inexperienced user.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
- <listitem>
- <para>
- Set the title of any tables being printed as the result of a
- query or unset any such title. This command is equivalent to
- <literal>\pset title <replaceable
- class="parameter">title</replaceable></literal>. (The name of
- this command derives from <quote>caption</quote>, as it was
- previously only used to set the caption in an
- <acronym>HTML</acronym> table.)
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>-t, --tuples-only</term>
+ <listitem>
+ <para>
+ Turn off printing of column names and result row count footers,
+ etc. It is completely equivalent to the <command>\t</command>
+ meta-command.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
- <listitem>
- <para>
- Establishes a connection to a new database and/or under a user
- name. The previous connection is closed. If <replaceable
- class="parameter">dbname</replaceable> is <literal>-</literal>
- the current database name is assumed.
- </para>
+ <varlistentry>
+ <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
+ <listitem>
+ <para>
+ Allows you to specify options to be placed within the
+ <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
+ <command>\pset</command> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-u</term>
+ <listitem>
+ <para>
+ Makes <application>psql</application> prompt for the user name and
+ password before connecting to the database.
+ </para>
- <para>
- If <replaceable class="parameter">username</replaceable> is
- omitted the current user name is assumed. </para>
+ <para>
+ This option is deprecated, as it is conceptually flawed.
+ (Prompting for a non-default user name and prompting for a
+ password because the backend requires it are really two different
+ things.) You are encouraged to look at the <option>-U</option> and
+ <option>-W</option> options instead.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- As a special rule, <command>\connect</command> without any
- arguments will connect to the default database as the default
- user (as you would have gotten by starting
- <application>psql</application> without any arguments).
- </para>
+ <varlistentry>
+ <term>-U, --username <replaceable class="parameter">username</replaceable></term>
+ <listitem>
+ <para>
+ Connects to the database as the user <replaceable
+ class="parameter">username</replaceable> instead of the default.
+ (You must have permission to do so, of course.)
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- If the connection attempt failed (wrong user name, access
- denied, etc.), the previous connection will be kept if and only
- if <application>psql</application> is in interactive mode. When
- executing a non-interactive script, processing will immediately
- stop with an error. This distinction was chosen as a user
- convenience against typos on the one hand, and a safety
- mechanism that scripts are not accidentally acting on the wrong
- database on the other hand.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
+ <listitem>
+ <para>
+ Performs a variable assignment, like the <command>\set</command>
+ internal command. Note that you must separate name and value, if
+ any, by an equal sign on the command line. To unset a variable,
+ leave off the equal sign. To just set a variable without a value,
+ use the equal sign but leave off the value. These assignments are
+ done during a very early stage of start-up, so variables reserved
+ for internal purposes might get overwritten later.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>\copy</literal> <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>' ]
- </term>
+ <varlistentry>
+ <term>-V, --version</term>
+ <listitem>
+ <para>
+ Shows the <application>psql</application> version.
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <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
- reading or writing the specified file, and consequently
- requiring backend access and special user privilege, as well as
- being bound to the file system accessible by the backend,
- <application>psql</application> reads or writes the file and
- routes the data between the backend and the local file system.
- </para>
+ <varlistentry>
+ <term>-W, --password</term>
+ <listitem>
+ <para>
+ Requests that <application>psql</application> should prompt for a
+ password before connecting to a database. This will remain set for
+ the entire session, even if you change the database connection
+ with the meta-command <command>\connect</command>.
+ </para>
- <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,
- special parsing rules apply to the <command>\copy</command>
- command. In particular, the variable substitution rules and
- backslash escapes do not apply.
- </para>
+ <para>
+ In the current version, <application>psql</application>
+ automatically issues a password prompt whenever the backend
+ requests password authentication. Because this is currently based
+ on a hack, the automatic recognition might mysteriously fail,
+ hence this option to force a prompt. If no password prompt is
+ issued and the backend requires password authentication the
+ connection attempt will fail.
+ </para>
+ </listitem>
+ </varlistentry>
- <tip>
- <para>
- This operation is not as efficient as the <acronym>SQL</acronym>
- <command>COPY</command> command because all data must pass
- through the client/server IP or socket connection. For large
- amounts of data the other technique may be preferable.
- </para>
- </tip>
+ <varlistentry>
+ <term>-x, --expanded</term>
+ <listitem>
+ <para>
+ Turns on extended row format mode. This is equivalent to the
+ command <command>\x</command>.
+ </para>
+ </listitem>
+ </varlistentry>
- <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
- 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
- <command>\o</command> meta-command below).
- </para>
- </note>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>-X, --no-psqlrc</term>
+ <listitem>
+ <para>
+ Do not read the start-up file <filename>~/.psqlrc</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><literal>\copyright</literal></term>
- <listitem>
- <para>
- Shows the copyright and distribution terms of
- <application>PostgreSQL</application>.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>-?, --help</term>
+ <listitem>
+ <para>
+ Shows help about <application>psql</application> command line
+ arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
- <varlistentry>
- <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
- <listitem>
- <para>
- Shows all columns of <replaceable
- class="parameter">relation</replaceable> (which could be a
- table, view, index, or sequence), their types, and any special
- attributes such as <literal>NOT NULL</literal> or defaults, if
- any. If the relation is, in fact, a table, any defined indices,
- primary keys, unique constraints and check constraints are also
- listed. If the relation is a view, the view definition is also
- shown.
- </para>
+ <refsect1>
+ <title>Exit Status</title>
- <para>
- The command form <literal>\d+</literal> is identical, but any
- comments associated with the table columns are shown as well.
- </para>
+ <para>
+ <application>psql</application> returns 0 to the shell if it
+ finished normally, 1 if a fatal error of its own (out of memory,
+ file not found) occurs, 2 if the connection to the backend went bad
+ and the session is not interactive, and 3 if an error occurred in a
+ script and the variable <envar>ON_ERROR_STOP</envar> was set.
+ </para>
+ </refsect1>
- <note>
- <para>
- If <command>\d</command> is called without any arguments, it is
- equivalent to <command>\dtvs</command> which will show a list of
- all tables, views, and sequences. This is purely a convenience
- measure.
- </para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+ <refsect1>
+ <title>Usage</title>
- <listitem>
- <para>
- Lists all available aggregate functions, together with the data
- type they operate on. If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
- is specified, only matching aggregates are shown.
- </para>
- </listitem>
- </varlistentry>
+ <refsect2 id="R2-APP-PSQL-connecting">
+ <title>Connecting To A Database</title>
- <varlistentry>
- <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
- <listitem>
- <para>
- Shows the descriptions of <replaceable
- class="parameter">object</replaceable> (which can be a regular
- expression), or of all objects if no argument is given.
- (<quote>Object</quote> covers aggregates, functions, operators,
- types, relations (tables, views, indexes, sequences, large
- objects), rules, and triggers.) For example:
-<programlisting>
-=> <userinput>\dd version</userinput>
- Object descriptions
- Name | What | Description
----------+----------+---------------------------
- version | function | PostgreSQL version string
-(1 row)
-</programlisting>
- </para>
+ <para>
+ <application>psql</application> is a regular
+ <productname>PostgreSQL</productname> client application. In order
+ to connect to a database you need to know the name of your target
+ database, the host name and port number of the server and what user
+ name you want to connect as. <application>psql</application> can be
+ told about those parameters via command line options, namely
+ <option>-d</option>, <option>-h</option>, <option>-p</option>, and
+ <option>-U</option> respectively. If an argument is found that does
+ not belong to any option it will be interpreted as the database name
+ (or the user name, if the database name is also given). Not all
+ these options are required, defaults do apply. If you omit the host
+ name psql will connect via a Unix domain socket to a server on the
+ local host. The default port number is compile-time determined.
+ Since the database server uses the same default, you will not have
+ to specify the port in most cases. The default user name is your
+ Unix user name, as is the default database name. Note that you can't
+ just connect to any database under any user name. Your database
+ administrator should have informed you about your access rights. To
+ save you some typing you can also set the environment variables
+ <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
+ <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
+ values.
+ </para>
- <para>
- Descriptions for objects can be generated with the
- <command>COMMENT ON</command> <acronym>SQL</acronym> command.
- </para>
+ <para>
+ If the connection could not be made for any reason (e.g., insufficient
+ privileges, postmaster is not running on the server, etc.),
+ <application>psql</application> will return an error and terminate.
+ </para>
+ </refsect2>
- <note>
- <para>
- <productname>PostgreSQL</productname> stores the object
- descriptions in the pg_description system table.
- </para>
- </note>
+ <refsect2 id="R2-APP-PSQL-4">
+ <title>Entering Queries</title>
- </listitem>
- </varlistentry>
+ <para>
+ In normal operation, <application>psql</application> provides a
+ prompt with the name of the database to which
+ <application>psql</application> is currently connected, followed by
+ the string <literal>=></literal>. For example,
+<programlisting>
+$ <userinput>psql testdb</userinput>
+Welcome to psql, the PostgreSQL interactive terminal.
+Type: \copyright for distribution terms
+ \h for help with SQL commands
+ \? for help on internal slash commands
+ \g or terminate with semicolon to execute query
+ \q to quit
- <varlistentry>
- <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
- <listitem>
- <para>
- Lists all available domains (derived types). If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
- is specified, only matching domains are shown.
- </para>
- </listitem>
- </varlistentry>
+testdb=>
+</programlisting>
+ </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
+ are displayed on the screen.
+ </para>
- <varlistentry>
- <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <para>
+ Whenever a query is executed, <application>psql</application> also polls
+ for asynchronous notification events generated by
+ <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
+ <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
+ </para>
+ </refsect2>
- <listitem>
- <para>
- Lists available functions, together with their argument and
- return types. If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
- is specified, only matching functions are shown. If the form
- <literal>\df+</literal> is used, additional information about
- each function, including language and description, is shown.
- </para>
- </listitem>
- </varlistentry>
+ <refsect2>
+ <title>Meta-Commands</title>
+ <para>
+ Anything you enter in <application>psql</application> that begins
+ with an unquoted backslash is a <application>psql</application>
+ meta-command that is processed by <application>psql</application>
+ itself. These commands are what makes
+ <application>psql</application> interesting for administration or
+ scripting. Meta-commands are more commonly called slash or backslash
+ commands.
+ </para>
- <varlistentry>
- <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <para>
+ The format of a <application>psql</application> command is the backslash,
+ followed immediately by a command verb, then any arguments. The arguments
+ are separated from the command verb and each other by any number of
+ whitespace characters.
+ </para>
- <listitem>
- <para>
- This is not the actual command name: The letters i, s, t, v, S
- stand for index, sequence, table, view, and system table,
- respectively. You can specify any or all of them in any order to
- obtain a listing of them, together with who the owner is.
- </para>
+ <para>
+ To include whitespace into an argument you must quote it with a
+ single quote. To include a single quote into such an argument,
+ precede it by a backslash. Anything contained in single quotes is
+ furthermore subject to C-like substitutions for
+ <literal>\n</literal> (new line), <literal>\t</literal> (tab),
+ <literal>\</literal><replaceable>digits</replaceable>,
+ <literal>\0</literal><replaceable>digits</replaceable>, and
+ <literal>\0x</literal><replaceable>digits</replaceable> (the
+ character with the given decimal, octal, or hexadecimal code).
+ </para>
- <para>
- If <replaceable class="parameter">pattern</replaceable> is
- specified, it is a regular expression that restricts the listing
- to those objects whose name matches. If one appends a
- <quote>+</quote> to the command name, each object is listed with
- its associated description, if any.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ If an unquoted argument begins with a colon (<literal>:</literal>),
+ it is taken as a variable and the value of the variable is taken as
+ the argument instead.
+ </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 a trailing newline
+ removed) is taken as the argument value. The above escape sequences
+ also apply in backticks.
+ </para>
+ <para>
+ Some commands take the name of an <acronym>SQL</acronym> identifier
+ (such as a table name) as argument. These arguments follow the
+ syntax rules of <acronym>SQL</acronym> regarding double quotes: an
+ identifier without double quotes is coerced to lower-case. For all
+ other commands double quotes are not special and will become part of
+ the argument.
+ </para>
- <varlistentry>
- <term><literal>\dl</literal></term>
- <listitem>
- <para>
- This is an alias for <command>\lo_list</command>, which shows a
- list of large objects.
- </para>
- </listitem>
- </varlistentry>
+ <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
+ any. That way <acronym>SQL</acronym> and
+ <application>psql</application> commands can be freely mixed on a
+ line. But in any case, the arguments of a meta-command cannot
+ continue beyond the end of the line.
+ </para>
+ <para>
+ The following meta-commands are defined:
+ <variablelist>
<varlistentry>
- <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
+ <term><literal>\a</literal></term>
<listitem>
<para>
- Lists available operators with their operand and return types.
- If <replaceable class="parameter">name</replaceable> is
- specified, only operators with that name will be shown.
+ If the current table output format is unaligned, switch to aligned.
+ If it is not unaligned, set it to unaligned. This command is
+ kept for backwards compatibility. See <command>\pset</command> for a
+ general solution.
</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
- <listitem>
- <para>
- This is an alias for <command>\z</command> which was included
- for its greater mnemonic value (<quote>display
- permissions</quote>).
- </para>
- </listitem>
- </varlistentry>
-
-
<varlistentry>
- <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
- <listitem>
+ <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
+ <listitem>
<para>
- Lists all data types or only those that match <replaceable
- class="parameter">pattern</replaceable>. The command form
- <literal>\dT+</literal> shows extra information.
+ Change the current working directory to
+ <replaceable>directory</replaceable>. Without argument, change
+ to the current user's home directory.
</para>
- </listitem>
- </varlistentry>
+ <tip>
+ <para>
+ To print your current working directory, use <literal>\!pwd</literal>.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
<varlistentry>
- <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
<listitem>
<para>
- Lists all configured users or only those that match <replaceable
- class="parameter">pattern</replaceable>.
+ Set the title of any tables being printed as the result of a
+ query or unset any such title. This command is equivalent to
+ <literal>\pset title <replaceable
+ class="parameter">title</replaceable></literal>. (The name of
+ this command derives from <quote>caption</quote>, as it was
+ previously only used to set the caption in an
+ <acronym>HTML</acronym> table.)
</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
-
+ <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
<listitem>
<para>
- If <replaceable class="parameter">filename</replaceable> is
- specified, the file is edited; after the editor exits, its
- content is copied back to the query buffer. If no argument is
- given, the current query buffer is copied to a temporary file
- which is then edited in the same fashion.
- </para>
-
- <para>
- The new query buffer is then re-parsed according to the normal
- rules of <application>psql</application>, where the whole buffer
- is treated as a single line. (Thus you cannot make scripts this
- way. Use <command>\i</command> for that.) This means also that
- if the query ends with (or rather contains) a semicolon, it is
- immediately executed. In other cases it will merely wait in the
- query buffer.
- </para>
-
- <tip>
- <para>
- <application>psql</application> searches the environment
- variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
- <envar>VISUAL</envar> (in that order) for an editor to use. If
- all of them are unset, <filename>/bin/vi</filename> is run.
- </para>
- </tip>
- </listitem>
- </varlistentry>
+ Establishes a connection to a new database and/or under a user
+ name. The previous connection is closed. If <replaceable
+ class="parameter">dbname</replaceable> is <literal>-</literal>
+ the current database name is assumed.
+ </para>
+ <para>
+ If <replaceable class="parameter">username</replaceable> is
+ omitted the current user name is assumed. </para>
- <varlistentry>
- <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
- <listitem>
<para>
- Prints the arguments to the standard output, separated by one
- space and followed by a newline. This can be useful to
- intersperse information in the output of scripts. For example:
-<programlisting>
-=> <userinput>\echo `date`</userinput>
-Tue Oct 26 21:40:57 CEST 1999
-</programlisting>
- If the first argument is an unquoted <literal>-n</literal> the the trailing
- newline is not written.
+ As a special rule, <command>\connect</command> without any
+ arguments will connect to the default database as the default
+ user (as you would have gotten by starting
+ <application>psql</application> without any arguments).
</para>
- <tip>
<para>
- If you use the <command>\o</command> command to redirect your
- query output you may wish to use <command>\qecho</command>
- instead of this command.
+ If the connection attempt failed (wrong user name, access
+ denied, etc.), the previous connection will be kept if and only
+ if <application>psql</application> is in interactive mode. When
+ executing a non-interactive script, processing will immediately
+ stop with an error. This distinction was chosen as a user
+ convenience against typos on the one hand, and a safety
+ mechanism that scripts are not accidentally acting on the wrong
+ database on the other hand.
</para>
- </tip>
- </listitem>
+ </listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
+ <term><literal>\copy</literal> <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>' ]
+ </term>
<listitem>
<para>
- Sets the client encoding, if you are using multibyte encodings.
- Without an argument, this command shows the current encoding.
- </para>
- </listitem>
- </varlistentry>
+ Performs a frontend (client) copy. This is an operation that
+ runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
+ endterm="SQL-COPY-title"> command, but instead of the backend's
+ reading or writing the specified file, and consequently
+ requiring backend access and special user privilege, as well as
+ being bound to the file system accessible by the backend,
+ <application>psql</application> reads or writes the file and
+ routes the data between the backend and the local file system.
+ </para>
+ <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,
+ special parsing rules apply to the <command>\copy</command>
+ command. In particular, the variable substitution rules and
+ backslash escapes do not apply.
+ </para>
- <varlistentry>
- <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
+ <tip>
+ <para>
+ This operation is not as efficient as the <acronym>SQL</acronym>
+ <command>COPY</command> command because all data must pass
+ through the client/server IP or socket connection. For large
+ amounts of data the other technique may be preferable.
+ </para>
+ </tip>
- <listitem>
+ <note>
<para>
- Sets the field separator for unaligned query output. The default
- is pipe (<literal>|</literal>). See also
- <command>\pset</command> for a generic way of setting output
- options.
+ Note the difference in interpretation of
+ <literal>stdin</literal> and <literal>stdout</literal> between
+ frontend and backend copies: in a frontend copy these always
+ refer to <application>psql</application>'s input and output
+ stream. On a backend copy <literal>stdin</literal> comes from
+ wherever the <command>COPY</command> itself came from (for
+ example, a script run with the <option>-f</option> option), and
+ <literal>stdout</literal> refers to the query output stream (see
+ <command>\o</command> meta-command below).
</para>
+ </note>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
-
+ <term><literal>\copyright</literal></term>
<listitem>
<para>
- Sends the current query input buffer to the backend and
- optionally saves the output in <replaceable
- class="parameter">filename</replaceable> or pipes the output
- into a separate Unix shell to execute <replaceable
- class="parameter">command</replaceable>. A bare
- <literal>\g</literal> is virtually equivalent to a semicolon. A
- <literal>\g</literal> with argument is a <quote>one-shot</quote>
- alternative to the <command>\o</command> command.
+ Shows the copyright and distribution terms of
+ <application>PostgreSQL</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
+ <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
+
<listitem>
<para>
- Give syntax help on the specified <acronym>SQL</acronym>
- command. If <replaceable class="parameter">command</replaceable>
- is not specified, then <application>psql</application> will list
- all the commands for which syntax help is available. If
- <replaceable class="parameter">command</replaceable> is an
- asterisk (<quote>*</quote>), then syntax help on all
- <acronym>SQL</acronym> commands is shown.
- </para>
+ Shows all columns of <replaceable
+ class="parameter">relation</replaceable> (which could be a
+ table, view, index, or sequence), their types, and any special
+ attributes such as <literal>NOT NULL</literal> or defaults, if
+ any. If the relation is, in fact, a table, any defined indices,
+ primary keys, unique constraints and check constraints are also
+ listed. If the relation is a view, the view definition is also
+ shown.
+ </para>
+
+ <para>
+ The command form <literal>\d+</literal> is identical, but any
+ comments associated with the table columns are shown as well.
+ </para>
<note>
<para>
- To simplify typing, commands that consists of several words do
- not have to be quoted. Thus it is fine to type <userinput>\help
- alter table</userinput>.
+ If <command>\d</command> is called without any arguments, it is
+ equivalent to <command>\dtvs</command> which will show a list of
+ all tables, views, and sequences. This is purely a convenience
+ measure.
</para>
- </note>
- </listitem>
+ </note>
+ </listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\H</literal></term>
+ <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+
<listitem>
<para>
- Turns on <acronym>HTML</acronym> query output format. If the
- <acronym>HTML</acronym> format is already on, it is switched
- back to the default aligned text format. This command is for
- compatibility and convenience, but see <command>\pset</command>
- about setting other output options.
+ Lists all available aggregate functions, together with the data
+ type they operate on. If <replaceable
+ class="parameter">pattern</replaceable> (a regular expression)
+ is specified, only matching aggregates are shown.
</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
+ <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
<listitem>
<para>
- Reads input from the file <replaceable
- class="parameter">filename</replaceable> and executes it as
- though it had been typed on the keyboard.
+ Shows the descriptions of <replaceable
+ class="parameter">object</replaceable> (which can be a regular
+ expression), or of all objects if no argument is given.
+ (<quote>Object</quote> covers aggregates, functions, operators,
+ types, relations (tables, views, indexes, sequences, large
+ objects), rules, and triggers.) For example:
+<programlisting>
+=> <userinput>\dd version</userinput>
+ Object descriptions
+ Name | What | Description
+---------+----------+---------------------------
+ version | function | PostgreSQL version string
+(1 row)
+</programlisting>
</para>
- <note>
- <para>
- If you want to see the lines on the screen as they are read you
- must set the variable <envar>ECHO</envar> to
- <literal>all</literal>.
+
+ <para>
+ Descriptions for objects can be generated with the
+ <command>COMMENT ON</command> <acronym>SQL</acronym> command.
</para>
- </note>
+
+ <note>
+ <para>
+ <productname>PostgreSQL</productname> stores the object
+ descriptions in the pg_description system table.
+ </para>
+ </note>
+
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\l</literal> (or <literal>\list</literal>)</term>
+ <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
<listitem>
<para>
- List all the databases in the server as well as their owners.
- Append a <quote>+</quote> to the command name to see any
- descriptions for the databases as well. If your
- <productname>PostgreSQL</productname> installation was compiled
- with multibyte encoding support, the encoding scheme of each
- database is shown as well.
+ Lists all available domains (derived types). If <replaceable
+ class="parameter">pattern</replaceable> (a regular expression)
+ is specified, only matching domains are shown.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
+ <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
- <listitem>
- <para>
- Reads the large object with <acronym>OID</acronym> <replaceable
- class="parameter">loid</replaceable> from the database and
- writes it to <replaceable
- class="parameter">filename</replaceable>. Note that this is
- subtly different from the server function
- <function>lo_export</function>, which acts with the permissions
- of the user that the database server runs as and on the server's
- file system.
- </para>
- <tip>
- <para>
- Use <command>\lo_list</command> to find out the large object's
- <acronym>OID</acronym>.
- </para>
- </tip>
- <note>
- <para>
- See the description of the <envar>LO_TRANSACTION</envar>
- variable for important information concerning all large object
- operations.
- </para>
- </note>
- </listitem>
+ <listitem>
+ <para>
+ Lists available functions, together with their argument and
+ return types. If <replaceable
+ class="parameter">pattern</replaceable> (a regular expression)
+ is specified, only matching functions are shown. If the form
+ <literal>\df+</literal> is used, additional information about
+ each function, including language and description, is shown.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
-
- <listitem>
- <para>
- Stores the file into a <productname>PostgreSQL</productname>
- <quote>large object</quote>. 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
- 152801 which one ought to remember if one wants to access the
- object ever again. For that reason it is recommended to always
- associate a human-readable comment with every object. Those can
- then be seen with the <command>\lo_list</command> command.
- </para>
+ <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <listitem>
<para>
- Note that this command is subtly different from the server-side
- <function>lo_import</function> because it acts as the local user
- on the local file system, rather than the server's user and file
- system.
+ This is not the actual command name: The letters i, s, t, v, S
+ stand for index, sequence, table, view, and system table,
+ respectively. You can specify any or all of them in any order to
+ obtain a listing of them, together with who the owner is.
</para>
- <note>
<para>
- See the description of the <envar>LO_TRANSACTION</envar>
- variable for important information concerning all large object
- operations.
+ If <replaceable class="parameter">pattern</replaceable> is
+ specified, it is a regular expression that restricts the listing
+ to those objects whose name matches. If one appends a
+ <quote>+</quote> to the command name, each object is listed with
+ its associated description, if any.
</para>
- </note>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>\lo_list</literal></term>
+ <term><literal>\dl</literal></term>
<listitem>
<para>
- Shows a list of all <productname>PostgreSQL</productname>
- <quote>large objects</quote> currently stored in the database,
- along with any comments provided for them.
+ This is an alias for <command>\lo_list</command>, which shows a
+ list of large objects.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
+ <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
+ <listitem>
+ <para>
+ Lists available operators with their operand and return types.
+ If <replaceable class="parameter">name</replaceable> is
+ specified, only operators with that name will be shown.
+ </para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>
- Deletes the large object with <acronym>OID</acronym>
- <replaceable class="parameter">loid</replaceable> from the
- database.
- </para>
- <tip>
- <para>
- Use <command>\lo_list</command> to find out the large object's
- <acronym>OID</acronym>.
- </para>
- </tip>
- <note>
+ <varlistentry>
+ <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+ <listitem>
<para>
- See the description of the <envar>LO_TRANSACTION</envar>
- variable for important information concerning all large object
- operations.
+ This is an alias for <command>\z</command> which was included
+ for its greater mnemonic value (<quote>display
+ permissions</quote>).
</para>
- </note>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>
-
+ <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
- Saves future query results to the file <replaceable
- class="parameter">filename</replaceable> or pipes future results
- into a separate Unix shell to execute <replaceable
- class="parameter">command</replaceable>. If no arguments are
- specified, the query output will be reset to
- <filename>stdout</filename>.
+ Lists all data types or only those that match <replaceable
+ class="parameter">pattern</replaceable>. The command form
+ <literal>\dT+</literal> shows extra information.
</para>
-
- <para>
- <quote>Query results</quote> includes all tables, command
- responses, and notices obtained from the database server, as
- well as output of various backslash commands that query the
- database (such as <command>\d</command>), but not error
- messages.
- </para>
-
- <tip>
- <para>
- To intersperse text output in between query results, use
- <command>\qecho</command>.
- </para>
- </tip>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\p</literal></term>
+ <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
- Print the current query buffer to the standard output.
+ Lists all configured users or only those that match <replaceable
+ class="parameter">pattern</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
-
- <listitem>
- <para>
- This command sets options affecting the output of query result
- tables. <replaceable class="parameter">parameter</replaceable>
- describes which option is to be set. The semantics of
- <replaceable class="parameter">value</replaceable> depend
- thereon.
- </para>
-
- <para>
- Adjustable printing options are:
- <variablelist>
- <varlistentry>
- <term><literal>format</literal></term>
- <listitem>
- <para>
- Sets the output format to one of <literal>unaligned</literal>,
- <literal>aligned</literal>, <literal>html</literal>, or
- <literal>latex</literal>. Unique abbreviations are allowed.
- (That would mean one letter is enough.)
- </para>
-
- <para>
- <quote>Unaligned</quote> writes all fields of a tuple on a
- line, separated by the currently active field separator. This
- is intended to create output that might be intended to be read
- in by other programs (tab-separated, comma-separated).
- <quote>Aligned</quote> mode is the standard, human-readable,
- nicely formatted text output that is default. The
- <quote><acronym>HTML</acronym></quote> and
- <quote>LaTeX</quote> modes put out tables that are intended to
- be included in documents using the respective mark-up
- language. They are not complete documents! (This might not be
- so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
- have a complete document wrapper.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>border</literal></term>
- <listitem>
- <para>
- The second argument must be a number. In general, the higher
- the number the more borders and lines the tables will have,
- but this depends on the particular format. In
- <acronym>HTML</acronym> mode, this will translate directly
- into the <literal>border=...</literal> attribute, in the
- others only values 0 (no border), 1 (internal dividing lines),
- and 2 (table frame) make sense.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>expanded</literal> (or <literal>x</literal>)</term>
- <listitem>
- <para>
- Toggles between regular and expanded format. When expanded
- format is enabled, all output has two columns with the field
- name on the left and the data on the right. This mode is
- useful if the data wouldn't fit on the screen in the normal
- <quote>horizontal</quote> mode.
- </para>
-
- <para>
- Expanded mode is supported by all four output modes.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>null</literal></term>
- <listitem>
- <para>
- The second argument is a string that should be printed
- whenever a field is null. The default is not to print
- anything, which can easily be mistaken for, say, an empty
- string. Thus, one might choose to write <literal>\pset null
- '(null)'</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>fieldsep</literal></term>
- <listitem>
- <para>
- Specifies the field separator to be used in unaligned output
- mode. That way one can create, for example, tab- or
- comma-separated output, which other programs might prefer. To
- set a tab as field separator, type <literal>\pset fieldsep
- '\t'</literal>. The default field separator is
- <literal>'|'</literal> (a <quote>pipe</quote> symbol).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>footer</literal></term>
- <listitem>
- <para>
- Toggles the display of the default footer <literal>(x
- rows)</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>recordsep</literal></term>
- <listitem>
- <para>
- Specifies the record (line) separator to use in unaligned
- output mode. The default is a newline character.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
- <listitem>
- <para>
- Toggles between tuples only and full display. Full display may
- show extra information such as column headers, titles, and
- various footers. In tuples only mode, only actual table data
- is shown.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
- <listitem>
- <para>
- Sets the table title for any subsequently printed tables. This
- can be used to give your output descriptive tags. If no
- argument is given, the title is unset.
- </para>
-
- <note>
- <para>
- This formerly only affected <acronym>HTML</acronym> mode. You
- can now set titles in any output format.
- </para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
- <listitem>
- <para>
- Allows you to specify any attributes to be placed inside the
- <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
- could for example be <literal>cellpadding</literal> or
- <literal>bgcolor</literal>. Note that you probably don't want
- to specify <literal>border</literal> here, as that is already
- taken care of by <literal>\pset border</literal>.
- </para>
- </listitem>
- </varlistentry>
+ <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
+ <listitem>
+ <para>
+ If <replaceable class="parameter">filename</replaceable> is
+ specified, the file is edited; after the editor exits, its
+ content is copied back to the query buffer. If no argument is
+ given, the current query buffer is copied to a temporary file
+ which is then edited in the same fashion.
+ </para>
- <varlistentry>
- <term><literal>pager</literal></term>
- <listitem>
- <para>
- Toggles the use of a pager for query and psql help output. If the
- environment variable <envar>PAGER</envar> is set, the output
- is piped to the specified program. Otherwise
- <filename>more</filename> is used.
- </para>
+ <para>
+ The new query buffer is then re-parsed according to the normal
+ rules of <application>psql</application>, where the whole buffer
+ is treated as a single line. (Thus you cannot make scripts this
+ way. Use <command>\i</command> for that.) This means also that
+ if the query ends with (or rather contains) a semicolon, it is
+ immediately executed. In other cases it will merely wait in the
+ query buffer.
+ </para>
- <para>
- In any case, <application>psql</application> only uses the
- pager if it seems appropriate. That means among other things
- that the output is to a terminal and that the table would
- normally not fit on the screen. Because of the modular nature
- of the printing routines it is not always possible to predict
- the number of lines that will actually be printed. For that
- reason <application>psql</application> might not appear very
- discriminating about when to use the pager.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- Illustrations on how these different formats look can be seen in
- the <xref linkend="APP-PSQL-examples"
- endterm="APP-PSQL-examples-title"> section.
+ <tip>
+ <para>
+ <application>psql</application> searches the environment
+ variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
+ <envar>VISUAL</envar> (in that order) for an editor to use. If
+ all of them are unset, <filename>/bin/vi</filename> is run.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
+ <listitem>
+ <para>
+ Prints the arguments to the standard output, separated by one
+ space and followed by a newline. This can be useful to
+ intersperse information in the output of scripts. For example:
+<programlisting>
+=> <userinput>\echo `date`</userinput>
+Tue Oct 26 21:40:57 CEST 1999
+</programlisting>
+ If the first argument is an unquoted <literal>-n</literal> the the trailing
+ newline is not written.
</para>
<tip>
<para>
- There are various shortcut commands for <command>\pset</command>. See
- <command>\a</command>, <command>\C</command>, <command>\H</command>,
- <command>\t</command>, <command>\T</command>, and <command>\x</command>.
+ If you use the <command>\o</command> command to redirect your
+ query output you may wish to use <command>\qecho</command>
+ instead of this command.
</para>
</tip>
+ </listitem>
+ </varlistentry>
- <note>
- <para>
- It is an error to call <command>\pset</command> without
- arguments. In the future this call might show the current status
- of all printing options.
- </para>
- </note>
- </listitem>
+ <varlistentry>
+ <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
+
+ <listitem>
+ <para>
+ Sets the client encoding, if you are using multibyte encodings.
+ Without an argument, this command shows the current encoding.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>\q</literal></term>
+ <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
+
<listitem>
<para>
- Quit the <application>psql</application> program.
+ Sets the field separator for unaligned query output. The default
+ is pipe (<literal>|</literal>). See also
+ <command>\pset</command> for a generic way of setting output
+ options.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
+ <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
+
<listitem>
<para>
- This command is identical to <command>\echo</command> except
- that all output will be written to the query output channel, as
- set by <command>\o</command>.
+ Sends the current query input buffer to the backend and
+ optionally saves the output in <replaceable
+ class="parameter">filename</replaceable> or pipes the output
+ into a separate Unix shell to execute <replaceable
+ class="parameter">command</replaceable>. A bare
+ <literal>\g</literal> is virtually equivalent to a semicolon. A
+ <literal>\g</literal> with argument is a <quote>one-shot</quote>
+ alternative to the <command>\o</command> command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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>
+ command. If <replaceable class="parameter">command</replaceable>
+ is not specified, then <application>psql</application> will list
+ all the commands for which syntax help is available. If
+ <replaceable class="parameter">command</replaceable> is an
+ asterisk (<quote>*</quote>), then syntax help on all
+ <acronym>SQL</acronym> commands is shown.
</para>
+
+ <note>
+ <para>
+ To simplify typing, commands that consists of several words do
+ not have to be quoted. Thus it is fine to type <userinput>\help
+ alter table</userinput>.
+ </para>
+ </note>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\r</literal></term>
+ <term><literal>\H</literal></term>
<listitem>
<para>
- Resets (clears) the query buffer.
+ Turns on <acronym>HTML</acronym> query output format. If the
+ <acronym>HTML</acronym> format is already on, it is switched
+ back to the default aligned text format. This command is for
+ compatibility and convenience, but see <command>\pset</command>
+ about setting other output options.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
+ <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
- Print or save the command line history to <replaceable
- class="parameter">filename</replaceable>. If <replaceable
- class="parameter">filename</replaceable> is omitted, the history
- is written to the standard output. This option is only available
- if <application>psql</application> is configured to use the
- <acronym>GNU</acronym> history library.
+ Reads input from the file <replaceable
+ class="parameter">filename</replaceable> and executes it as
+ though it had been typed on the keyboard.
+ </para>
+ <note>
+ <para>
+ If you want to see the lines on the screen as they are read you
+ must set the variable <envar>ECHO</envar> to
+ <literal>all</literal>.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><literal>\l</literal> (or <literal>\list</literal>)</term>
+ <listitem>
+ <para>
+ List all the databases in the server as well as their owners.
+ Append a <quote>+</quote> to the command name to see any
+ descriptions for the databases as well. If your
+ <productname>PostgreSQL</productname> installation was compiled
+ with multibyte encoding support, the encoding scheme of each
+ database is shown as well.
</para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
+
+ <listitem>
+ <para>
+ Reads the large object with <acronym>OID</acronym> <replaceable
+ class="parameter">loid</replaceable> from the database and
+ writes it to <replaceable
+ class="parameter">filename</replaceable>. Note that this is
+ subtly different from the server function
+ <function>lo_export</function>, which acts with the permissions
+ of the user that the database server runs as and on the server's
+ file system.
+ </para>
+ <tip>
+ <para>
+ Use <command>\lo_list</command> to find out the large object's
+ <acronym>OID</acronym>.
+ </para>
+ </tip>
+ <note>
+ <para>
+ See the description of the <envar>LO_TRANSACTION</envar>
+ variable for important information concerning all large object
+ operations.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
+
+ <listitem>
+ <para>
+ Stores the file into a <productname>PostgreSQL</productname>
+ <quote>large object</quote>. 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
+ 152801 which one ought to remember if one wants to access the
+ object ever again. For that reason it is recommended to always
+ associate a human-readable comment with every object. Those can
+ then be seen with the <command>\lo_list</command> command.
+ </para>
+
+ <para>
+ Note that this command is subtly different from the server-side
+ <function>lo_import</function> because it acts as the local user
+ on the local file system, rather than the server's user and file
+ system.
+ </para>
<note>
<para>
- In the current version, it is no longer necessary to save the
- command history, since that will be done automatically on
- program termination. The history is also loaded automatically
- every time <application>psql</application> starts up.
+ See the description of the <envar>LO_TRANSACTION</envar>
+ variable for important information concerning all large object
+ operations.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>\lo_list</literal></term>
+ <listitem>
+ <para>
+ Shows a list of all <productname>PostgreSQL</productname>
+ <quote>large objects</quote> currently stored in the database,
+ along with any comments provided for them.
</para>
- </note>
- </listitem>
+ </listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
+ <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
<listitem>
<para>
- Sets the internal variable <replaceable
- class="parameter">name</replaceable> to <replaceable
- class="parameter">value</replaceable> or, if more than one value
- is given, to the concatenation of all of them. If no second
- argument is given, the variable is just set with no value. To
- unset a variable, use the <command>\unset</command> command.
- </para>
-
- <para>
- Valid variable names can contain characters, digits, and
- underscores. See the section about
- <application>psql</application> variables for details.
+ Deletes the large object with <acronym>OID</acronym>
+ <replaceable class="parameter">loid</replaceable> from the
+ database.
</para>
+ <tip>
<para>
- Although you are welcome to set any variable to anything you
- want, <application>psql</application> treats several variables
- as special. They are documented in the section about variables.
+ Use <command>\lo_list</command> to find out the large object's
+ <acronym>OID</acronym>.
</para>
-
+ </tip>
<note>
<para>
- This command is totally separate from the <acronym>SQL</acronym>
- command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
+ See the description of the <envar>LO_TRANSACTION</envar>
+ variable for important information concerning all large object
+ operations.
</para>
</note>
</listitem>
<varlistentry>
- <term><literal>\t</literal></term>
- <listitem>
- <para>
- Toggles the display of output column name headings and row count
- footer. This command is equivalent to <literal>\pset
- tuples_only</literal> and is provided for convenience.
- </para>
- </listitem>
- </varlistentry>
-
+ <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>
- <varlistentry>
- <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
<listitem>
<para>
- Allows you to specify options to be placed within the
- <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
- output mode. This command is equivalent to <literal>\pset
- tableattr <replaceable
- class="parameter">table_options</replaceable></literal>.
+ Saves future query results to the file <replaceable
+ class="parameter">filename</replaceable> or pipes future results
+ into a separate Unix shell to execute <replaceable
+ class="parameter">command</replaceable>. If no arguments are
+ specified, the query output will be reset to
+ <filename>stdout</filename>.
</para>
- </listitem>
- </varlistentry>
+ <para>
+ <quote>Query results</quote> includes all tables, command
+ responses, and notices obtained from the database server, as
+ well as output of various backslash commands that query the
+ database (such as <command>\d</command>), but not error
+ messages.
+ </para>
- <varlistentry>
- <term><literal>\timing</literal></term>
- <listitem>
- <para>
- Toggles a display of how long each query takes in seconds.
- </para>
- </listitem>
+ <tip>
+ <para>
+ To intersperse text output in between query results, use
+ <command>\qecho</command>.
+ </para>
+ </tip>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+ <term><literal>\p</literal></term>
<listitem>
<para>
- Outputs the current query buffer to the file <replaceable
- class="parameter">filename</replaceable> or pipes it to the Unix
- command <replaceable class="parameter">command</replaceable>.
+ Print the current query buffer to the standard output.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\x</literal></term>
- <listitem>
- <para>
- Toggles extended row format mode. As such it is equivalent to
- <literal>\pset expanded</literal>.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
- <listitem>
- <para>
- Produces a list of all tables in the database with their
- appropriate access permissions listed. If an argument is given
- it is taken as a regular expression which limits the listing to
- those tables which match it.
- </para>
+ <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
+ <listitem>
<para>
-<programlisting>
-test=> <userinput>\z</userinput>
-Access permissions for database "test"
- Relation | Access permissions
-----------+-------------------------------------
- my_table | {"=r","joe=arwR", "group staff=ar"}
-(1 row )
-</programlisting>
- Read this as follows:
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
- (<command>SELECT</command>) permission on the table.
- </para>
- </listitem>
+ This command sets options affecting the output of query result
+ tables. <replaceable class="parameter">parameter</replaceable>
+ describes which option is to be set. The semantics of
+ <replaceable class="parameter">value</replaceable> depend
+ thereon.
+ </para>
+ <para>
+ Adjustable printing options are:
+ <variablelist>
+ <varlistentry>
+ <term><literal>format</literal></term>
<listitem>
<para>
- <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
- read, write (<command>UPDATE</command>,
- <command>DELETE</command>), <quote>append</quote>
- (<command>INSERT</command>) permissions, and permission to
- create rules on the table.
+ Sets the output format to one of <literal>unaligned</literal>,
+ <literal>aligned</literal>, <literal>html</literal>, or
+ <literal>latex</literal>. Unique abbreviations are allowed.
+ (That would mean one letter is enough.)
</para>
- </listitem>
- <listitem>
<para>
- <literal>"group staff=ar"</literal>: Group
- <literal>staff</literal> has <command>SELECT</command> and
- <command>INSERT</command> permission.
+ <quote>Unaligned</quote> writes all fields of a tuple on a
+ line, separated by the currently active field separator. This
+ is intended to create output that might be intended to be read
+ in by other programs (tab-separated, comma-separated).
+ <quote>Aligned</quote> mode is the standard, human-readable,
+ nicely formatted text output that is default. The
+ <quote><acronym>HTML</acronym></quote> and
+ <quote>LaTeX</quote> modes put out tables that are intended to
+ be included in documents using the respective mark-up
+ language. They are not complete documents! (This might not be
+ so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
+ have a complete document wrapper.)
</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- The commands <xref linkend="SQL-GRANT"> and
- <xref linkend="SQL-REVOKE">
- are used to set access permissions.
- </para>
-
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
- <listitem>
- <para>
- Escapes to a separate Unix shell or executes the Unix command
- <replaceable class="parameter">command</replaceable>. The
- arguments are not further interpreted, the shell will see them
- as is.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><literal>\?</literal></term>
- <listitem>
- <para>
- Get help information about the backslash (<quote>\</quote>)
- commands.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
-</refsect1>
-
-
-
-<refsect1 id="R1-APP-PSQL-3">
- <refsect1info>
- <date>1998-09-26</date>
- </refsect1info>
-
- <title>Command-line Options</title>
-
- <para>
- If so configured, <application>psql</application> understands both
- standard Unix short options, and <acronym>GNU</acronym>-style long
- options. The latter are not available on all systems.
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>-a, --echo-all</term>
- <listitem>
- <para>
- Print all the lines to the screen as they are read. This is more
- useful for script processing rather than interactive mode. This is
- equivalent to setting the variable <envar>ECHO</envar> to
- <literal>all</literal>.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>-A, --no-align</term>
- <listitem>
- <para>
- Switches to unaligned output mode. (The default output mode is
- otherwise aligned.)
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>-c, --command <replaceable class="parameter">query</replaceable></term>
- <listitem>
- <para>
- Specifies that <application>psql</application> is to execute one
- query string, <replaceable class="parameter">query</replaceable>,
- and then exit. This is useful in shell scripts.
- </para>
- <para>
- <replaceable class="parameter">query</replaceable> must be either
- a query string that is completely parseable by the backend (i.e.,
- it contains no <application>psql</application> specific features),
- or it is a single backslash command. Thus you cannot mix
- <acronym>SQL</acronym> and <application>psql</application>
- meta-commands. To achieve that, you could pipe the string into
- <application>psql</application>, like this: <literal>echo "\x \\
- select * from foo;" | psql</literal>.
- </para>
- </listitem>
- </varlistentry>
-
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
- <listitem>
- <para>
- Specifies the name of the database to connect to. This is
- equivalent to specifying <replaceable
- class="parameter">dbname</replaceable> as the first non-option
- argument on the command line.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>border</literal></term>
+ <listitem>
+ <para>
+ The second argument must be a number. In general, the higher
+ the number the more borders and lines the tables will have,
+ but this depends on the particular format. In
+ <acronym>HTML</acronym> mode, this will translate directly
+ into the <literal>border=...</literal> attribute, in the
+ others only values 0 (no border), 1 (internal dividing lines),
+ and 2 (table frame) make sense.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>expanded</literal> (or <literal>x</literal>)</term>
+ <listitem>
+ <para>
+ Toggles between regular and expanded format. When expanded
+ format is enabled, all output has two columns with the field
+ name on the left and the data on the right. This mode is
+ useful if the data wouldn't fit on the screen in the normal
+ <quote>horizontal</quote> mode.
+ </para>
- <varlistentry>
- <term>-e, --echo-queries</term>
- <listitem>
- <para>
- Show all queries that are sent to the backend. This is equivalent
- to setting the variable <envar>ECHO</envar> to
- <literal>queries</literal>.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ Expanded mode is supported by all four output modes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>null</literal></term>
+ <listitem>
+ <para>
+ The second argument is a string that should be printed
+ whenever a field is null. The default is not to print
+ anything, which can easily be mistaken for, say, an empty
+ string. Thus, one might choose to write <literal>\pset null
+ '(null)'</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-E, --echo-hidden</term>
- <listitem>
- <para>
- Echoes the actual queries generated by \d and other backslash
- commands. You can use this if you wish to include similar
- functionality into your own programs. This is equivalent to
- setting the variable <envar>ECHO_HIDDEN</envar> from within
- <application>psql</application>.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>fieldsep</literal></term>
+ <listitem>
+ <para>
+ Specifies the field separator to be used in unaligned output
+ mode. That way one can create, for example, tab- or
+ comma-separated output, which other programs might prefer. To
+ set a tab as field separator, type <literal>\pset fieldsep
+ '\t'</literal>. The default field separator is
+ <literal>'|'</literal> (a <quote>pipe</quote> symbol).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>footer</literal></term>
+ <listitem>
+ <para>
+ Toggles the display of the default footer <literal>(x
+ rows)</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
- <listitem>
- <para>
- Use the file <replaceable class="parameter">filename</replaceable>
- as the source of queries instead of reading queries interactively.
- After the file is processed, <application>psql</application>
- terminates. This is in many ways equivalent to the internal
- command <command>\i</command>.
- </para>
+ <varlistentry>
+ <term><literal>recordsep</literal></term>
+ <listitem>
+ <para>
+ Specifies the record (line) separator to use in unaligned
+ output mode. The default is a newline character.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- If <replaceable>filename</replaceable> is <literal>-</literal>
- (hyphen), then standard input is read.
- </para>
+ <varlistentry>
+ <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
+ <listitem>
+ <para>
+ Toggles between tuples only and full display. Full display may
+ show extra information such as column headers, titles, and
+ various footers. In tuples only mode, only actual table data
+ is shown.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- Using this option is subtly different from writing <literal>psql
- < <replaceable
- class="parameter">filename</replaceable></literal>. In general,
- both will do what you expect, but using <literal>-f</literal>
- enables some nice features such as error messages with line
- numbers. There is also a slight chance that using this option will
- reduce the start-up overhead. On the other hand, the variant using
- the shell's input redirection is (in theory) guaranteed to yield
- exactly the same output that you would have gotten had you entered
- everything by hand.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
+ <listitem>
+ <para>
+ Sets the table title for any subsequently printed tables. This
+ can be used to give your output descriptive tags. If no
+ argument is given, the title is unset.
+ </para>
+ <note>
+ <para>
+ This formerly only affected <acronym>HTML</acronym> mode. You
+ can now set titles in any output format.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
- <listitem>
- <para>
- Use <replaceable class="parameter">separator</replaceable> as the
- field separator. This is equivalent to <command>\pset
- fieldsep</command> or <command>\f</command>.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
+ <listitem>
+ <para>
+ Allows you to specify any attributes to be placed inside the
+ <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
+ could for example be <literal>cellpadding</literal> or
+ <literal>bgcolor</literal>. Note that you probably don't want
+ to specify <literal>border</literal> here, as that is already
+ taken care of by <literal>\pset border</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
- <listitem>
- <para>
- Specifies the host name of the machine on which the
- <application>postmaster</application> is running. If host begins
- with a slash, it is used as the directory for the unix domain
- socket.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>pager</literal></term>
+ <listitem>
+ <para>
+ Toggles the use of a pager for query and psql help output. If the
+ environment variable <envar>PAGER</envar> is set, the output
+ is piped to the specified program. Otherwise a platform-dependent default (such as
+ <filename>more</filename>) is used.
+ </para>
+ <para>
+ In any case, <application>psql</application> only uses the
+ pager if it seems appropriate. That means among other things
+ that the output is to a terminal and that the table would
+ normally not fit on the screen. Because of the modular nature
+ of the printing routines it is not always possible to predict
+ the number of lines that will actually be printed. For that
+ reason <application>psql</application> might not appear very
+ discriminating about when to use the pager.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Illustrations on how these different formats look can be seen in
+ the <xref linkend="APP-PSQL-examples"
+ endterm="APP-PSQL-examples-title"> section.
+ </para>
- <varlistentry>
- <term>-H, --html</term>
- <listitem>
- <para>
- Turns on <acronym>HTML</acronym> tabular output. This is
- equivalent to <literal>\pset format html</literal> or the
- <command>\H</command> command.
- </para>
- </listitem>
- </varlistentry>
+ <tip>
+ <para>
+ There are various shortcut commands for <command>\pset</command>. See
+ <command>\a</command>, <command>\C</command>, <command>\H</command>,
+ <command>\t</command>, <command>\T</command>, and <command>\x</command>.
+ </para>
+ </tip>
-
- <varlistentry>
- <term>-l, --list</term>
- <listitem>
- <para>
- Lists all available databases, then exits. Other non-connection
- options are ignored. This is similar to the internal command
- <command>\list</command>.
- </para>
- </listitem>
- </varlistentry>
+ <note>
+ <para>
+ It is an error to call <command>\pset</command> without
+ arguments. In the future this call might show the current status
+ of all printing options.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
- <listitem>
- <para>
- Put all query output into file <replaceable
- class="parameter">filename</replaceable>. This is equivalent to
- the command <command>\o</command>.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\q</literal></term>
+ <listitem>
+ <para>
+ Quit the <application>psql</application> program.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-p, --port <replaceable class="parameter">port</replaceable></term>
- <listitem>
- <para>
- Specifies the TCP/IP port or, by omission, the local Unix domain
- socket file extension on which the
- <application>postmaster</application> is listening for
- connections. Defaults to the value of the <envar>PGPORT</envar>
- environment variable or, if not set, to the port specified at
- compile time, usually 5432.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
+ <listitem>
+ <para>
+ This command is identical to <command>\echo</command> except
+ that all output will be written to the query output channel, as
+ set by <command>\o</command>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
- <listitem>
- <para>
- Allows you to specify printing options in the style of
- <command>\pset</command> on the command line. Note that here you
- have to separate name and value with an equal sign instead of a
- space. Thus to set the output format to LaTeX, you could write
- <literal>-P format=latex</literal>.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\r</literal></term>
+ <listitem>
+ <para>
+ Resets (clears) the query buffer.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-q</term>
- <listitem>
- <para>
- Specifies that <application>psql</application> should do its work
- quietly. By default, it prints welcome messages and various
- informational output. If this option is used, none of this
- happens. This is useful with the <option>-c</option> option.
- Within <application>psql</application> you can also set the
- <envar>QUIET</envar> variable to achieve the same effect.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
+ <listitem>
+ <para>
+ Print or save the command line history to <replaceable
+ class="parameter">filename</replaceable>. If <replaceable
+ class="parameter">filename</replaceable> is omitted, the history
+ is written to the standard output. This option is only available
+ if <application>psql</application> is configured to use the
+ <acronym>GNU</acronym> history library.
+ </para>
- <varlistentry>
- <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
- <listitem>
- <para>
- Use <replaceable class="parameter">separator</replaceable> as the
- record separator. This is equivalent to the <command>\pset
- recordsep</command> command.
- </para>
- </listitem>
- </varlistentry>
+ <note>
+ <para>
+ In the current version, it is no longer necessary to save the
+ command history, since that will be done automatically on
+ program termination. The history is also loaded automatically
+ every time <application>psql</application> starts up.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
-
- <varlistentry>
- <term>-s, --single-step</term>
- <listitem>
- <para>
- Run in single-step mode. That means the user is prompted before
- each query is sent to the backend, with the option to cancel
- execution as well. Use this to debug scripts.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
- <varlistentry>
- <term>-S, --single-line</term>
- <listitem>
- <para>
- Runs in single-line mode where a newline terminates a query, as a
- semicolon does.
- </para>
+ <listitem>
+ <para>
+ Sets the internal variable <replaceable
+ class="parameter">name</replaceable> to <replaceable
+ class="parameter">value</replaceable> or, if more than one value
+ is given, to the concatenation of all of them. If no second
+ argument is given, the variable is just set with no value. To
+ unset a variable, use the <command>\unset</command> command.
+ </para>
- <note>
- <para>
- This mode is provided for those who insist on it, but you are not
- necessarily encouraged to use it. In particular, if you mix
- <acronym>SQL</acronym> and meta-commands on a line the order of
- execution might not always be clear to the inexperienced user.
- </para>
- </note>
- </listitem>
- </varlistentry>
+ <para>
+ Valid variable names can contain characters, digits, and
+ underscores. See the section about
+ <application>psql</application> variables for details.
+ </para>
+ <para>
+ Although you are welcome to set any variable to anything you
+ want, <application>psql</application> treats several variables
+ as special. They are documented in the section about variables.
+ </para>
- <varlistentry>
- <term>-t, --tuples-only</term>
- <listitem>
- <para>
- Turn off printing of column names and result row count footers,
- etc. It is completely equivalent to the <command>\t</command>
- meta-command.
- </para>
- </listitem>
- </varlistentry>
+ <note>
+ <para>
+ This command is totally separate from the <acronym>SQL</acronym>
+ command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
- <listitem>
- <para>
- Allows you to specify options to be placed within the
- <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
- <command>\pset</command> for details.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\t</literal></term>
+ <listitem>
+ Toggles the display of output column name headings and row count
+ footer. This command is equivalent to <literal>\pset
+ tuples_only</literal> and is provided for convenience.
+ </para>
+ </listitem>
+ </varlistentry>
-
- <varlistentry>
- <term>-u</term>
- <listitem>
- <para>
- Makes <application>psql</application> prompt for the user name and
- password before connecting to the database.
- </para>
- <para>
- This option is deprecated, as it is conceptually flawed.
- (Prompting for a non-default user name and prompting for a
- password because the backend requires it are really two different
- things.) You are encouraged to look at the <option>-U</option> and
- <option>-W</option> options instead.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
+ <listitem>
+ <para>
+ Allows you to specify options to be placed within the
+ <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
+ output mode. This command is equivalent to <literal>\pset
+ tableattr <replaceable
+ class="parameter">table_options</replaceable></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-U, --username <replaceable class="parameter">username</replaceable></term>
- <listitem>
- <para>
- Connects to the database as the user <replaceable
- class="parameter">username</replaceable> instead of the default.
- (You must have permission to do so, of course.)
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\timing</literal></term>
+ <listitem>
+ <para>
+ Toggles a display of how long each query takes in seconds.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
- <listitem>
- <para>
- Performs a variable assignment, like the <command>\set</command>
- internal command. Note that you must separate name and value, if
- any, by an equal sign on the command line. To unset a variable,
- leave off the equal sign. To just set a variable without a value,
- use the equal sign but leave off the value. These assignments are
- done during a very early stage of start-up, so variables reserved
- for internal purposes might get overwritten later.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+ <listitem>
+ <para>
+ Outputs the current query buffer to the file <replaceable
+ class="parameter">filename</replaceable> or pipes it to the Unix
+ command <replaceable class="parameter">command</replaceable>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-V, --version</term>
- <listitem>
- <para>
- Shows the <application>psql</application> version.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term><literal>\x</literal></term>
+ <listitem>
+ <para>
+ Toggles extended row format mode. As such it is equivalent to
+ <literal>\pset expanded</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-W, --password</term>
- <listitem>
- <para>
- Requests that <application>psql</application> should prompt for a
- password before connecting to a database. This will remain set for
- the entire session, even if you change the database connection
- with the meta-command <command>\connect</command>.
- </para>
+ <varlistentry>
+ <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+ <listitem>
+ Produces a list of all tables in the database with their
+ appropriate access permissions listed. If an argument is given
+ it is taken as a regular expression which limits the listing to
+ those tables which match it.
+ </para>
- <para>
- In the current version, <application>psql</application>
- automatically issues a password prompt whenever the backend
- requests password authentication. Because this is currently based
- on a hack, the automatic recognition might mysteriously fail,
- hence this option to force a prompt. If no password prompt is
- issued and the backend requires password authentication the
- connection attempt will fail.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+<programlisting>
+test=> <userinput>\z</userinput>
+Access permissions for database "test"
+ Relation | Access permissions
+----------+-------------------------------------
+ my_table | {"=r","joe=arwR", "group staff=ar"}
+(1 row )
+</programlisting>
+ Read this as follows:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
+ (<command>SELECT</command>) permission on the table.
+ </para>
+ </listitem>
- <varlistentry>
- <term>-x, --expanded</term>
- <listitem>
- <para>
- Turns on extended row format mode. This is equivalent to the
- command <command>\x</command>.
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
+ read, write (<command>UPDATE</command>,
+ <command>DELETE</command>), <quote>append</quote>
+ (<command>INSERT</command>) permissions, and permission to
+ create rules on the table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>"group staff=ar"</literal>: Group
+ <literal>staff</literal> has <command>SELECT</command> and
+ <command>INSERT</command> permission.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
- <varlistentry>
- <term>-X, --no-psqlrc</term>
- <listitem>
- <para>
- Do not read the start-up file <filename>~/.psqlrc</filename>.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ The commands <xref linkend="SQL-GRANT"> and
+ <xref linkend="SQL-REVOKE">
+ are used to set access permissions.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>-?, --help</term>
- <listitem>
- <para>
- Shows help about <application>psql</application> command line
- arguments.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <varlistentry>
+ <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
+ <listitem>
+ <para>
+ Escapes to a separate Unix shell or executes the Unix command
+ <replaceable class="parameter">command</replaceable>. The
+ arguments are not further interpreted, the shell will see them
+ as is.
+ </para>
+ </listitem>
+ </varlistentry>
-</refsect1>
+ <varlistentry>
+ <term><literal>\?</literal></term>
+ <listitem>
+ <para>
+ Get help information about the backslash (<quote>\</quote>)
+ commands.
+ </para>
+ </listitem>
+ </varlistentry>
-<refsect1 id="R1-APP-PSQL-4">
- <refsect1info>
- <date>1998-09-27</date>
- </refsect1info>
+ </variablelist>
+ </para>
+ </refsect2>
- <title>Advanced features</title>
+ <refsect2>
+ <title>Advanced features</title>
- <refsect2 id="APP-PSQL-variables">
+ <refsect3 id="APP-PSQL-variables">
<title id="APP-PSQL-variables-title">Variables</title>
<para>
</para>
- </refsect2>
-
+ </refsect3>
- <refsect2 id="APP-PSQL-sql-interpol">
- <title
id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title>
+ <refsect3>
+ <title><acronym>SQL</acronym> Interpolation</title>
<para>
An additional useful feature of <application>psql</application>
conflict.)
</para>
- </refsect2>
-
+ </refsect3>
- <refsect2 id="APP-PSQL-prompting">
+ <refsect3 id="APP-PSQL-prompting">
<title id="APP-PSQL-prompting-title">Prompting</title>
<para>
</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>ON_ERROR_STOP</envar> was set.
- </para>
-
- <para>
- Before starting up, <application>psql</application> attempts to read
- and execute commands from the file
- <filename>$HOME/.psqlrc</filename>. It could be used to set up the
- client or the server to taste (using the <command>\set </command>
- and <command>SET</command> commands).
- </para>
-
- </refsect2>
+ </refsect3>
- <refsect2>
- <title><acronym>GNU</acronym> readline</title>
+ <refsect3>
+ <title>Readline</title>
<para>
<application>psql</application> supports the readline and history
<acronym>GNU</acronym> project's <acronym>FTP</acronym> server at
<ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
</para>
+ </refsect3>
</refsect2>
+ </refsect1>
+
+
+ <refsect1>
+ <title>Environment</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><envar>HOME</envar></term>
+
+ <listitem>
+ <para>
+ Directory for initialization file (<filename>.psqlrc</filename>)
+ and command history file (<filename>.psql_history</filename>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PAGER</envar></term>
+
+ <listitem>
+ <para>
+ If the query results do not fit on the screen, they are piped
+ through this command. Typical values are
+ <literal>more</literal> or <literal>less</literal>. The default
+ is platform-dependent. The use of the pager can be disabled by
+ using the <command>\pset</command> command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGDATABASE</envar></term>
+
+ <listitem>
+ <para>
+ Default database to connect to
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PGHOST</envar></term>
+ <term><envar>PGPORT</envar></term>
+ <term><envar>PGUSER</envar></term>
+
+ <listitem>
+ <para>
+ Default connection parameters
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>PSQL_EDITOR</envar></term>
+ <term><envar>EDITOR</envar></term>
+ <term><envar>VISUAL</envar></term>
+
+ <listitem>
+ <para>
+ Editor used by the <command>\e</command> command. The variables
+ are examined in the order listed; the first that is set is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>SHELL</envar></term>
+
+ <listitem>
+ <para>
+ Command executed by the <command>\!</command> command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><envar>TMPDIR</envar></term>
+
+ <listitem>
+ <para>
+ Directory for storing temporary files. The default is
+ <filename>/tmp</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+ <title>Files</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Before starting up, <application>psql</application> attempts to
+ read and execute commands from the file
+ <filename>$HOME/.psqlrc</filename>. It could be used to set up
+ the client or the server to taste (using the <command>\set
+ </command> and <command>SET</command> commands).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The command-line history is stored in the file
+ <filename>$HOME/.psql_history</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+
+ <refsect1>
+ <title>Notes</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ In some earlier life <application>psql</application> allowed the
+ first argument to start directly after the (single-letter)
+ command. For compatibility this is still supported to some extent
+ but I am not going to explain the details here as this use is
+ discouraged. But if you get strange messages, keep this in mind.
+ For example
+<programlisting>
+testdb=> <userinput>\foo</userinput>
+Field separator is "oo",
+</programlisting>
+ which is perhaps not what one would expect.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>psql</application> only works smoothly with servers
+ of the same version. That does not mean other combinations will
+ fail outright, but subtle and not-so-subtle problems might come
+ up.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Pressing Control-C during a <quote>copy in</quote> (data sent to
+ the server) doesn't show the most ideal of behaviors. If you get a
+ message such as <quote>COPY state must be terminated
+ first</quote>, simply reset the connection by entering <literal>\c
+ - -</literal>.
+ </para>
+ </listitem>
-</refsect1>
+ </itemizedlist>
+ </refsect1>
-<refsect1 id="APP-PSQL-examples">
+ <refsect1 id="APP-PSQL-examples">
<title id="APP-PSQL-examples-title">Examples</title>
<note>
</programlisting>
</para>
-</refsect1>
-
-
-<refsect1>
- <refsect1info>
- <date>1999-10-27</date>
- </refsect1info>
-
- <title>Appendix</title>
-
- <refsect2>
- <title>Bugs and Issues</title>
-
- <itemizedlist>
- <listitem>
- <para>
- In some earlier life <application>psql</application> allowed the
- first argument to start directly after the (single-letter)
- command. For compatibility this is still supported to some extent
- but I am not going to explain the details here as this use is
- discouraged. But if you get strange messages, keep this in mind.
- For example
-<programlisting>
-testdb=> <userinput>\foo</userinput>
-Field separator is "oo",
-</programlisting>
- which is perhaps not what one would expect.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <application>psql</application> only works smoothly with servers
- of the same version. That does not mean other combinations will
- fail outright, but subtle and not-so-subtle problems might come
- up.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Pressing Control-C during a <quote>copy in</quote> (data sent to
- the server) doesn't show the most ideal of behaviors. If you get a
- message such as <quote>COPY state must be terminated
- first</quote>, simply reset the connection by entering <literal>\c
- - -</literal>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </refsect2>
-
-</refsect1>
+ </refsect1>
</refentry>
projects / postgresql / commitdiff