database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

Improve psql's behavior for \set and \unset of its control variables.

Browse Source 
This commit improves on the results of commit 511ae628f in two ways:

1. It restores the historical behavior that "\set FOO" is interpreted
as setting FOO to "on", if FOO is a boolean control variable.  We
already found one test script that was expecting that behavior, and
the psql documentation certainly does nothing to discourage people
from assuming that would work, since it often says just "if FOO is set"
when describing the effects of a boolean variable.  However, now this
case will result in actually setting FOO to "on", not an empty string.

2. It arranges for an "\unset" of a control variable to set the value
back to its default value, rather than becoming apparently undefined.
The control variables are also initialized that way at psql startup.

In combination, these things guarantee that a control variable always
has a displayable value that reflects what psql is actually doing.
That is a pretty substantial usability improvement.

The implementation involves adding a second type of variable hook function
that is able to replace a proposed new value (including NULL) with another
one.  We could alternatively have complicated the API of the assign hook,
but this way seems better since many variables can share the same
substitution hook function.

Also document the actual behavior of these variables more fully,
including covering assorted behaviors that were there before but
never documented.

This patch also includes some minor cleanup that should have been in
511ae628f but was missed.

Patch by me, but it owes a lot to discussions with Daniel Vérité.

Discussion: https://postgr.es/m/9572.1485821620@sss.pgh.pa.us
This commit is contained in:
Tom Lane
2017-02-01 11:02:40 -05:00
parent dbd69118c0
commit 86322dc7e0
6 changed files with 319 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -455,8 +455,8 @@ EOF
any, by an equal sign on the command line. To unset a variable,
leave off the equal sign. To set a variable with an empty 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.
done during command line processing, so variables that reflect
connection state will get overwritten later.
</para>
</listitem>
</varlistentry>
@ -2692,7 +2692,7 @@ lo_import 152801
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 only one
argument is given, the variable is set with an empty value. To
argument is given, the variable is set to an empty-string value. To
unset a variable, use the <command>\unset</command> command.
</para>
@ -2709,9 +2709,11 @@ lo_import 152801
</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.
Certain variables are special, in that they
control <application>psql</application>'s behavior or are
automatically set to reflect connection state. These variables are
documented in <xref linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title">, below.
</para>
<note>
@ -2835,6 +2837,14 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
Unsets (deletes) the <application>psql</> variable <replaceable
class="parameter">name</replaceable>.
</para>
<para>
Most variables that control <application>psql</application>'s behavior
cannot be unset; instead, an <literal>\unset</> command is interpreted
as setting them to their default values.
See <xref linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title">, below.
</para>
</listitem>
</varlistentry>
@ -3053,7 +3063,7 @@ bar
<para>
If you call <command>\set</command> without a second argument, the
variable is set, with an empty string as value. To unset (i.e., delete)
variable is set to an empty-string value. To unset (i.e., delete)
a variable, use the command <command>\unset</command>. To show the
values of all variables, call <command>\set</command> without any argument.
</para>
@ -3082,8 +3092,23 @@ bar
By convention, all specially treated variables' names
consist of all upper-case ASCII letters (and possibly digits and
underscores). To ensure maximum compatibility in the future, avoid
using such variable names for your own purposes. A list of all specially
treated variables follows.
using such variable names for your own purposes.
</para>
<para>
Variables that control <application>psql</application>'s behavior
generally cannot be unset or set to invalid values. An <literal>\unset</>
command is allowed but is interpreted as setting the variable to its
default value. A <literal>\set</> command without a second argument is
interpreted as setting the variable to <literal>on</>, for control
variables that accept that value, and is rejected for others. Also,
control variables that accept the values <literal>on</>
and <literal>off</> will also accept other common spellings of Boolean
values, such as <literal>true</> and <literal>false</>.
</para>
<para>
The specially treated variables are:
</para>
<variablelist>
@ -3153,7 +3178,7 @@ bar
<para>
The name of the database you are currently connected to. This is
set every time you connect to a database (including program
start-up), but can be unset.
start-up), but can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -3171,8 +3196,8 @@ bar
as it is sent to the server. The switch to select this behavior is
<option>-e</option>. If set to <literal>errors</literal>, then only
failed queries are displayed on standard error output. The switch
for this behavior is <option>-b</option>. If unset, or if set to
<literal>none</literal>, then no queries are displayed.
for this behavior is <option>-b</option>. If set to
<literal>none</literal> (the default), then no queries are displayed.
</para>
</listitem>
</varlistentry>
@ -3187,8 +3212,9 @@ bar
<productname>PostgreSQL</productname> internals and provide
similar functionality in your own programs. (To select this behavior
on program start-up, use the switch <option>-E</option>.) If you set
the variable to the value <literal>noexec</literal>, the queries are
this variable to the value <literal>noexec</literal>, the queries are
just shown but are not actually sent to the server and executed.
The default value is <literal>off</>.
</para>
</listitem>
</varlistentry>
@ -3200,7 +3226,7 @@ bar
The current client character set encoding.
This is set every time you connect to a database (including
program start-up), and when you change the encoding
with <literal>\encoding</>, but it can be unset.
with <literal>\encoding</>, but it can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -3209,7 +3235,7 @@ bar
<term><varname>FETCH_COUNT</varname></term>
<listitem>
<para>
If this variable is set to an integer value &gt; 0,
If this variable is set to an integer value greater than zero,
the results of <command>SELECT</command> queries are fetched
and displayed in groups of that many rows, rather than the
default behavior of collecting the entire result set before
@ -3220,6 +3246,13 @@ bar
Keep in mind that when using this feature, a query might
fail after having already displayed some rows.
</para>
<para>
<varname>FETCH_COUNT</varname> is ignored if it is unset or does not
have a positive value. It cannot be set to a value that is not
syntactically an integer.
</para>
<tip>
<para>
Although you can use any output format with this feature,
@ -3241,7 +3274,7 @@ bar
list. If set to a value of <literal>ignoredups</literal>, lines
matching the previous history line are not entered. A value of
<literal>ignoreboth</literal> combines the two options. If
unset, or if set to <literal>none</literal> (the default), all lines
set to <literal>none</literal> (the default), all lines
read in interactive mode are saved on the history list.
</para>
<note>
@ -3257,8 +3290,12 @@ bar
<term><varname>HISTFILE</varname></term>
<listitem>
<para>
The file name that will be used to store the history list. The default
value is <filename>~/.psql_history</filename>. For example, putting:
The file name that will be used to store the history list. If unset,
the file name is taken from the <envar>PSQL_HISTORY</envar>
environment variable. If that is not set either, the default
is <filename>~/.psql_history</filename>,
or <filename>%APPDATA%\postgresql\psql_history</filename> on Windows.
For example, putting:
<programlisting>
\set HISTFILE ~/.psql_history- :DBNAME
</programlisting>
@ -3279,8 +3316,10 @@ bar
<term><varname>HISTSIZE</varname></term>
<listitem>
<para>
The number of commands to store in the command history. The
default value is 500.
The maximum number of commands to store in the command history.
If unset, at most 500 commands are stored by default.
If set to a value that is negative or not an integer, no limit is
applied.
</para>
<note>
<para>
@ -3297,7 +3336,7 @@ bar
<para>
The database server host you are currently connected to. This is
set every time you connect to a database (including program
start-up), but can be unset.
start-up), but can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -3350,7 +3389,7 @@ bar
generates an error, the error is ignored and the transaction
continues. When set to <literal>interactive</>, such errors are only
ignored in interactive sessions, and not when reading script
files. When unset or set to <literal>off</>, a statement in a
files. When set to <literal>off</> (the default), a statement in a
transaction block that generates an error aborts the entire
transaction. The error rollback mode works by issuing an
implicit <command>SAVEPOINT</> for you, just before each command
@ -3385,7 +3424,7 @@ bar
<para>
The database server port to which you are currently connected.
This is set every time you connect to a database (including
program start-up), but can be unset.
program start-up), but can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -3458,7 +3497,7 @@ bar
<para>
The database user you are currently connected as. This is set
every time you connect to a database (including program
start-up), but can be unset.
start-up), but can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -3481,7 +3520,7 @@ bar
<listitem>
<para>
This variable is set at program start-up to
reflect <application>psql</>'s version. It can be unset or changed.
reflect <application>psql</>'s version. It can be changed or unset.
</para>
</listitem>
</varlistentry>
@ -4015,6 +4054,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
</para>
<para>
The location of the history file can be set explicitly via
the <varname>HISTFILE</varname> <application>psql</> variable or
the <envar>PSQL_HISTORY</envar> environment variable.
</para>
</listitem>