From 86322dc7e013b4062393dcbb74043db003e23ec5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 1 Feb 2017 11:02:40 -0500 Subject: Improve psql's behavior for \set and \unset of its control variables. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/src/sgml/ref/psql-ref.sgml | 90 ++++++++++++++++++++++++++++++------------ 1 file changed, 65 insertions(+), 25 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 4e51e90906c..b9c8fccde43 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -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. @@ -2692,7 +2692,7 @@ lo_import 152801 class="parameter">name to value, 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 \unset command. @@ -2709,9 +2709,11 @@ lo_import 152801 - Although you are welcome to set any variable to anything you - want, psql treats several variables - as special. They are documented in the section about variables. + Certain variables are special, in that they + control psql's behavior or are + automatically set to reflect connection state. These variables are + documented in , below. @@ -2835,6 +2837,14 @@ testdb=> \setenv LESS -imx4F Unsets (deletes) the psql variable name. + + + Most variables that control psql's behavior + cannot be unset; instead, an \unset command is interpreted + as setting them to their default values. + See , below. + @@ -3053,7 +3063,7 @@ bar If you call \set 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 \unset. To show the values of all variables, call \set without any argument. @@ -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. + + + + Variables that control psql's behavior + generally cannot be unset or set to invalid values. An \unset + command is allowed but is interpreted as setting the variable to its + default value. A \set command without a second argument is + interpreted as setting the variable to on, for control + variables that accept that value, and is rejected for others. Also, + control variables that accept the values on + and off will also accept other common spellings of Boolean + values, such as true and false. + + + + The specially treated variables are: @@ -3153,7 +3178,7 @@ bar 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. @@ -3171,8 +3196,8 @@ bar as it is sent to the server. The switch to select this behavior is . If set to errors, then only failed queries are displayed on standard error output. The switch - for this behavior is . If unset, or if set to - none, then no queries are displayed. + for this behavior is . If set to + none (the default), then no queries are displayed. @@ -3187,8 +3212,9 @@ bar PostgreSQL internals and provide similar functionality in your own programs. (To select this behavior on program start-up, use the switch .) If you set - the variable to the value noexec, the queries are + this variable to the value noexec, the queries are just shown but are not actually sent to the server and executed. + The default value is off. @@ -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 \encoding, but it can be unset. + with \encoding, but it can be changed or unset. @@ -3209,7 +3235,7 @@ bar FETCH_COUNT - If this variable is set to an integer value > 0, + If this variable is set to an integer value greater than zero, the results of SELECT 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. + + + FETCH_COUNT 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. + + Although you can use any output format with this feature, @@ -3241,7 +3274,7 @@ bar list. If set to a value of ignoredups, lines matching the previous history line are not entered. A value of ignoreboth combines the two options. If - unset, or if set to none (the default), all lines + set to none (the default), all lines read in interactive mode are saved on the history list. @@ -3257,8 +3290,12 @@ bar HISTFILE - The file name that will be used to store the history list. The default - value is ~/.psql_history. For example, putting: + The file name that will be used to store the history list. If unset, + the file name is taken from the PSQL_HISTORY + environment variable. If that is not set either, the default + is ~/.psql_history, + or %APPDATA%\postgresql\psql_history on Windows. + For example, putting: \set HISTFILE ~/.psql_history- :DBNAME @@ -3279,8 +3316,10 @@ bar HISTSIZE - 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. @@ -3297,7 +3336,7 @@ bar 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. @@ -3350,7 +3389,7 @@ bar generates an error, the error is ignored and the transaction continues. When set to interactive, such errors are only ignored in interactive sessions, and not when reading script - files. When unset or set to off, a statement in a + files. When set to 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 SAVEPOINT for you, just before each command @@ -3385,7 +3424,7 @@ bar 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. @@ -3458,7 +3497,7 @@ bar 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. @@ -3481,7 +3520,7 @@ bar This variable is set at program start-up to - reflect psql's version. It can be unset or changed. + reflect psql's version. It can be changed or unset. @@ -4015,6 +4054,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' The location of the history file can be set explicitly via + the HISTFILE psql variable or the PSQL_HISTORY environment variable. -- cgit v1.2.3