From f9ebf36970df6e61142dbe7590482cd240fdb66a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 28 Jun 2003 00:12:40 +0000 Subject: Update psql for some features of new FE/BE protocol. There is a client-side AUTOCOMMIT mode now: '\set AUTOCOMMIT off' supports SQL-spec commit behavior. Get rid of LO_TRANSACTION hack --- the LO operations just work now, using libpq's ability to track the transaction status. Add a VERBOSE variable to control verboseness of error message display, and add a %T prompt-string code to show current transaction-block status. Superuser state display in the prompt string correctly follows SET SESSION AUTHORIZATION commands. Control-C works to get out of COPY IN state. --- doc/src/sgml/ref/psql-ref.sgml | 179 ++++++++++++++++++++--------------------- doc/src/sgml/release.sgml | 4 +- 2 files changed, 89 insertions(+), 94 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 8dd25d572e4..a3501e0bdab 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -1200,13 +1200,6 @@ Tue Oct 26 21:40:57 CEST 1999 OID. - - - See the description of the LO_TRANSACTION - variable for important information concerning all large object - operations. - - @@ -1236,14 +1229,6 @@ lo_import 152801 on the local file system, rather than the server's user and file system. - - - - See the description of the LO_TRANSACTION - variable for important information concerning all large object - operations. - - @@ -1274,13 +1259,6 @@ lo_import 152801 OID. - - - See the description of the LO_TRANSACTION - variable for important information concerning all large object - operations. - - @@ -1809,14 +1787,14 @@ bar If you call \set without a second argument, the - variable is simply set, but has no value. To unset (or delete) a + variable is set, with an empty string as value. To unset (or delete) a variable, use the command \unset. psql's internal variable names can consist of letters, numbers, and underscores in any order and any - number of them. A number of regular variables are treated specially + number of them. A number of these variables are treated specially by psql. They indicate certain option settings that can be changed at run time by altering the value of the variable or represent some state of the application. Although @@ -1825,10 +1803,47 @@ bar really quickly. By convention, all specially treated variables consist of all upper-case letters (and possibly numbers and underscores). To ensure maximum compatibility in the future, avoid - such variables. A list of all specially treated variables follows. + using such variable names for your own purposes. A list of all specially + treated variables follows. + + AUTOCOMMIT + + + When on (the default), each SQL command is automatically + committed upon successful completion. To postpone commit in this + mode, you must enter a BEGIN or START + TRANSACTION SQL command. When off or unset, SQL + commands are not committed until you explicitly issue + COMMIT or END. The autocommit-off + mode works by issuing an implicit BEGIN for you, just + before any command that is not already in a transaction block and + is not itself a BEGIN or other transaction-control + command. + + + + + In autocommit-off mode, you must explicitly abandon any failed + transaction by entering ABORT or ROLLBACK. + Also keep in mind that if you exit the session + without committing, your work will be lost. + + + + + + The autocommit-on mode is PostgreSQL's traditional + behavior, but autocommit-off is closer to the SQL spec. If you + prefer autocommit-off, you may wish to set it in + your .psqlrc file. + + + + + DBNAME @@ -1846,11 +1861,11 @@ bar If set to all, all lines entered or from a script are written to the standard output - before they are parsed or executed. To specify this on program + before they are parsed or executed. To select this behavior on program start-up, use the switch . If set to queries, psql merely prints all queries as - they are sent to the server. The option for this is + they are sent to the server. The switch for this is . @@ -1863,10 +1878,10 @@ bar When this variable is set and a backslash command queries the database, the query is first shown. This way you can study the PostgreSQL internals and provide - similar functionality in your own programs. If you set the - variable to the value noexec, the queries are - just shown but are not actually sent to the server and - executed. + 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 + just shown but are not actually sent to the server and executed. @@ -1962,39 +1977,6 @@ bar - - LO_TRANSACTION - - - If you use the PostgreSQL large - object interface to specially store data that does not fit into - one row, all the operations must be contained in a transaction - block. (See the documentation of the large object interface for - more information.) Since psql has no - way to tell if you already have a transaction in progress when - you call one of its internal commands - (\lo_export, \lo_import, - \lo_unlink) it must take some arbitrary - action. This action could either be to roll back any transaction - that might already be in progress, or to commit any such - transaction, or to do nothing at all. In the last case you must - provide your own BEGIN/COMMIT block or the - results will be unpredictable (usually resulting in the desired - action's not being performed in any case). - - - - To choose what you want to do you set this variable to one of - rollback, commit, or - nothing. The default is to roll back the - transaction. If you just want to load one or a few objects this - is fine. However, if you intend to transfer many large objects, - it might be advisable to provide one explicit transaction block - around all commands. - - - - ON_ERROR_STOP @@ -2032,8 +2014,8 @@ bar PROMPT3 - These specify what the prompt psql - issues is supposed to look like. See psql + issues should look like. See below. @@ -2055,8 +2037,8 @@ bar SINGLELINE - This variable is set by the command line option - . You can unset or reset it at run time. + This variable is equivalent to the command line option + . @@ -2082,6 +2064,17 @@ bar + + VERBOSE + + + This variable can be set to the values default, + verbose, or terse to control the verbosity + of error reports. + + + + @@ -2123,7 +2116,7 @@ testdb=> INSERT INTO my_table VALUES (:content); testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'' - Observe the correct number of backslashes (6)! You can resolve it + Observe the correct number of backslashes (6)! It works this way: After psql has parsed this line, it passes sed -e "s/'/\\\'/g" < my_file.txt to the shell. The shell will do its own thing inside the double @@ -2141,9 +2134,10 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' Since colons may legally appear in SQL commands, the following rule - applies: If the variable is not set, the character sequence - colon+name is not changed. In any case you can escape - a colon with a backslash to protect it from interpretation. (The + applies: the character sequence + :name is not changed unless name is the name + of a variable that is currently set. In any case you can escape + a colon with a backslash to protect it from substitution. (The colon syntax for variables is standard SQL for embedded query languages, such as ECPG. The colon syntax for array slices and type casts are @@ -2171,7 +2165,7 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' - The value of the respective prompt variable is printed literally, + The value of the selected prompt variable is printed literally, except where a percent sign (%) is encountered. Depending on the next character, certain other text is substituted instead. Defined substitutions are: @@ -2243,7 +2237,20 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' psql expects more input because the command wasn't terminated yet, because you are inside a /* ... */ comment, or because you are inside - a quote. In prompt 3 the sequence doesn't resolve to anything. + a quote. In prompt 3 the sequence doesn't produce anything. + + + + + + %T + + + Transaction status: an empty string when not in a transaction + block, or * when in a transaction block, or + ! when in a failed transaction block, or ? + when the transaction state is indeterminate (for example, because + there is no connection). @@ -2252,13 +2259,12 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' %digits + The character with the indicated numeric code is substituted. If digits starts with 0x the rest of the characters are - interpreted as a hexadecimal digit and the character with the - corresponding code is substituted. If the first digit is - 0 the characters are interpreted as on octal - number and the corresponding character is substituted. Otherwise - a decimal number is assumed. + interpreted as hexadecimal; otherwise if the first digit is + 0 the digits are interpreted as octal; + otherwise the digits are read as a decimal number. @@ -2289,7 +2295,7 @@ testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' To insert a percent sign into your prompt, write - %%. The default prompts are equivalent to + %%. The default prompts are '%/%R%# ' for prompts 1 and 2, and '>> ' for prompt 3. @@ -2473,17 +2479,6 @@ Field separator is "oo". - - - Pressing ControlC - during a copy in (data sent to - the server) doesn't show the most ideal of behaviors. If you get a - message such as COPY state must be terminated - first, simply reset the connection by entering \c - - -. - - - diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index cc03ae9cbe3..188f2c8341b 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ @@ -31,7 +31,7 @@ Functional indexes have been generalized into expressional indexes CHAR(n) to TEXT conversion automatically strips trailing blanks Pattern matching operations can use indexes regardless of locale New frontend/backend protocol supports many long-requested features -SET AUTOCOMMIT TO OFF is no longer supported +SET AUTOCOMMIT TO OFF is no longer supported; psql has an AUTOCOMMIT variable Reimplementation of NUMERIC datatype for more speed New regular expression package, many more regexp features (most of Perl5) Can now do EXPLAIN ... EXECUTE to see plan used for a prepared query -- cgit v1.2.3