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

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index ad463e71c10082fa342025023b8b638b43d986bd..8f43a1c8b39341623f73158d5b65f66c08aec589 100644 (file)
--- 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 
+        specified, the file is edited; after the editor exits, the file's
+        content is copied into the current query buffer. If no 
         class="parameter">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 
-        class="parameter">filename or pipes the output
-        to the shell command 
-        class="parameter">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 
          linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title">).
          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 
+        Writes the current query buffer to the file 
         class="parameter">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.
+        
         
       
 




This is the main PostgreSQL git repository.
RSS
Atom



window.onload = function () {
	var tz_cookie = { name: 'gitweb_tz', expires: 14, path: '/' };
	onloadTZSetup('local', tz_cookie, 'datetime');
};