diff options
Diffstat (limited to 'doc/src/sgml/ref/psql-ref.sgml')
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 1143 |
1 files changed, 583 insertions, 560 deletions
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 923a8741112..b9f8554abfb 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,13 +1,9 @@ <!-- -$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> @@ -21,19 +17,17 @@ PostgreSQL documentation </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 @@ -44,23 +38,412 @@ PostgreSQL documentation 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> + + <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>-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> + + <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>-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> + + <para> + If <replaceable>filename</replaceable> is <literal>-</literal> + (hyphen), then standard input is read. + </para> + + <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>-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>-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>-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> + + <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>-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>-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>-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>-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>-S, --single-line</term> + <listitem> + <para> + Runs in single-line mode where a newline terminates a query, as a + semicolon does. + </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> + + <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>-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> + 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>-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>-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>-V, --version</term> + <listitem> + <para> + Shows the <application>psql</application> version. + </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> + + <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> + + <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> + + <varlistentry> + <term>-X, --no-psqlrc</term> + <listitem> + <para> + Do not read the start-up file <filename>~/.psqlrc</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Shows help about <application>psql</application> command line + arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Exit Status</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> + </refsect1> + + + <refsect1> + <title>Usage</title> <refsect2 id="R2-APP-PSQL-connecting"> - <refsect2info> - <date>2000-01-14</date> - </refsect2info> - <title>Connecting To A Database</title> <para> @@ -96,10 +479,6 @@ PostgreSQL documentation </refsect2> <refsect2 id="R2-APP-PSQL-4"> - <refsect2info> - <date>1998-09-26</date> - </refsect2info> - <title>Entering Queries</title> <para> @@ -137,14 +516,9 @@ testdb=> <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">. </para> </refsect2> -</refsect1> -<refsect1 id="R1-APP-PSQL-2"> - <refsect1info> - <date>1998-09-26</date> - </refsect1info> - - <title><application>psql</application> Meta-Commands</title> + <refsect2> + <title>Meta-Commands</title> <para> Anything you enter in <application>psql</application> that begins @@ -1038,8 +1412,8 @@ lo_import 152801 <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. + is piped to the specified program. Otherwise a platform-dependent default (such as + <filename>more</filename>) is used. </para> <para> @@ -1314,440 +1688,12 @@ Access permissions for database "test" </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> - - - <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>-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> - - - <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>-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> - - <para> - If <replaceable>filename</replaceable> is <literal>-</literal> - (hyphen), then standard input is read. - </para> - - <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>-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>-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>-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> - - - <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>-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>-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>-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>-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>-S, --single-line</term> - <listitem> - <para> - Runs in single-line mode where a newline terminates a query, as a - semicolon does. - </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> - - - <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>-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> - 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>-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>-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>-V, --version</term> - <listitem> - <para> - Shows the <application>psql</application> version. - </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> - - <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> - - - <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> - - - <varlistentry> - <term>-X, --no-psqlrc</term> - <listitem> - <para> - Do not read the start-up file <filename>~/.psqlrc</filename>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-?, --help</term> - <listitem> - <para> - Shows help about <application>psql</application> command line - arguments. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - -</refsect1> - - -<refsect1 id="R1-APP-PSQL-4"> - <refsect1info> - <date>1998-09-27</date> - </refsect1info> + </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> @@ -2063,11 +2009,10 @@ bar </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> @@ -2131,10 +2076,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' conflict.) </para> - </refsect2> - + </refsect3> - <refsect2 id="APP-PSQL-prompting"> + <refsect3 id="APP-PSQL-prompting"> <title id="APP-PSQL-prompting-title">Prompting</title> <para> @@ -2282,31 +2226,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' </para> </note> - </refsect2> + </refsect3> - <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> - - <refsect2> - <title><acronym>GNU</acronym> readline</title> + <refsect3> + <title>Readline</title> <para> <application>psql</application> supports the readline and history @@ -2356,14 +2279,167 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ... <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> @@ -2478,60 +2554,7 @@ second | four </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> |