From 68dba97a4dea5c5c915e31978a475107c17c458d Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 2 Apr 2017 18:26:37 -0400 Subject: [PATCH] Document psql's behavior of recalling the previously executed query. Various psql slash commands that normally act on the current query buffer will automatically recall and re-use the most recently executed SQL command instead, if the current query buffer is empty. Although this behavior is ancient (dating apparently to commit 77a472993), it was documented nowhere in the psql reference page. For that matter, we'd never bothered to define the concept of "current query buffer" explicitly. Fix that. Do some wordsmithing on relevant command descriptions to improve clarity and consistency. Discussion: https://postgr.es/m/9b4ea968-753f-4b5f-b46c-d7d3bf7c8f90@manitou-mail.org --- doc/src/sgml/ref/psql-ref.sgml | 73 ++++++++++++++++++++++++---------- 1 file changed, 52 insertions(+), 21 deletions(-) diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index ad463e71c1..8f43a1c8b3 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -823,6 +823,14 @@ testdb=> continue beyond the end of the line. + + Many of the meta-commands act on the current query buffer. + This is simply a buffer holding whatever SQL command text has been typed + but not yet sent to the server for execution. This will include previous + input lines as well as any text appearing before the meta-command on the + same line. + + The following meta-commands are defined: @@ -1713,22 +1721,28 @@ testdb=> If filename is - specified, the file is edited; after the editor exits, its - content is copied back to the query buffer. If no filename is given, the current query buffer is copied to a temporary file which is then edited in the same + fashion. Or, if the current query buffer is empty, the most recently + executed query is copied to a temporary file and edited in the same fashion. - The new query buffer is then re-parsed according to the normal - rules of psql, where the whole buffer - is treated as a single line. (Thus you cannot make scripts this - way. Use \i for that.) This means that - if the query ends with (or contains) a semicolon, it is - immediately executed. Otherwise it will merely wait in the - query buffer; type semicolon or \g to send it, or - \r to cancel. + The new contents of the query buffer are then re-parsed according to + the normal rules of psql, treating the + whole buffer as a single line. Any complete queries are immediately + executed; that is, if the query buffer contains or ends with a + semicolon, everything up to that point is executed. Whatever remains + will wait in the query buffer; type semicolon or \g to + send it, or \r to cancel it by clearing the query buffer. + Treating the buffer as a single line primarily affects meta-commands: + whatever is in the buffer after a meta-command will be taken as + argument(s) to the meta-command, even if it spans multiple lines. + (Thus you cannot make meta-command-using scripts this way. + Use \i for that.) @@ -1888,16 +1902,17 @@ Tue Oct 26 21:40:57 CEST 1999 \g [ |command ] - Sends the current query input buffer to the server, and - optionally stores the query's output in filename or pipes the output - to the shell command command. The file or command is - written to only if the query successfully returns zero or more tuples, - not if the query fails or is a non-data-returning SQL command. + Sends the current query buffer to the server for execution. + If an argument is given, the query's output is written to the named + file or piped to the given shell command, instead of displaying it as + usual. The file or command is written to only if the query + successfully returns zero or more tuples, not if the query fails or + is a non-data-returning SQL command. - A bare \g is essentially equivalent to a semicolon. + If the current query buffer is empty, the most recently sent query is + re-executed instead. Except for that behavior, \g + without an argument is essentially equivalent to a semicolon. A \g with argument is a one-shot alternative to the \o command. @@ -1922,7 +1937,7 @@ Tue Oct 26 21:40:57 CEST 1999 - Sends the current query input buffer to the server, then treats + Sends the current query buffer to the server, then treats each column of each row of the query's output (if any) as a SQL statement to be executed. For example, to create an index on each column of my_table: @@ -1955,6 +1970,10 @@ CREATE INDEX timing, and other query execution features apply to each generated query as well. + + If the current query buffer is empty, the most recently sent query + is re-executed instead. + @@ -1964,7 +1983,7 @@ CREATE INDEX - Sends the current query input buffer to the server and stores the + Sends the current query buffer to the server and stores the query's output into psql variables (see ). The query to be executed must return exactly one row. Each column of @@ -1996,6 +2015,10 @@ hello 10 If the query fails or does not return one row, no variables are changed. + + If the current query buffer is empty, the most recently sent query + is re-executed instead. + @@ -2302,6 +2325,8 @@ lo_import 152801 Print the current query buffer to the standard output. + If the current query buffer is empty, the most recently executed query + is printed instead. @@ -2970,9 +2995,11 @@ testdb=> \setenv LESS -imx4F \w or \write |command - Outputs the current query buffer to the file filename or pipes it to the shell command command. + If the current query buffer is empty, the most recently executed query + is written instead. @@ -2988,6 +3015,10 @@ testdb=> \setenv LESS -imx4F displayed with a header that includes the \pset title string (if any), the time as of query start, and the delay interval. + + If the current query buffer is empty, the most recently sent query + is re-executed instead. + -- 2.40.0