psql: Rename meta-command \close to \close_prepared

\close has been introduced in d55322b0da60 to be able to close a
prepared statement using the extended protocol in psql.  Per discussion,
the name "close" is ambiguous.  At the SQL level, CLOSE is used to close
a cursor.  At protocol level, the close message can be used to either
close a statement or a portal.

This patch renames \close to \close_prepared to avoid any ambiguity and
make it clear that this is used to close a prepared statement.  This new
name has been chosen based on the feedback from the author and the
reviewers.

Author: Anthonin Bonnefoy 
Reviewed-by: Peter Eisentraut 
Reviewed-by: Jelte Fennema-Nio 
Discussion: https://postgr.es/m/3e694442-0df5-4f92-a08f-c5d4c4346b85@eisentraut.org

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 570ef21d1fce3abe70eae8eafb9ff4678641174a..95f4cac2467e315654a0ab2edf990b257b00888d 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1067,8 +1067,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
        
       
 
-      
-       \close prepared_statement_name
+      -prepared">
+       \close_prepared prepared_statement_name
 
        
         
@@ -1081,7 +1081,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
          Example:
 
 SELECT $1 \parse stmt1
-\close stmt1
+\close_prepared stmt1
 
         
 
@@ -3710,7 +3710,7 @@ testdb=> \setenv LESS -imx4F
         All queries executed while a pipeline is ongoing use the extended
         query protocol. Queries are appended to the pipeline when ending with
         a semicolon. The meta-commands \bind,
-        \bind_named, \close or
+        \bind_named, \close_prepared or
         \parse can be used in an ongoing pipeline. While
         a pipeline is ongoing, \sendpipeline will append
         the current query buffer to the pipeline. Other meta-commands like

diff --git a/doc/src/sgml/release-18.sgml b/doc/src/sgml/release-18.sgml
index 662c7d8890f9b170a689ac5b726e330f78c93e13..66a6817a2be0fececd9998c7bfe67ffb9f125402 100644 (file)
--- a/doc/src/sgml/release-18.sgml
+++ b/doc/src/sgml/release-18.sgml
@@ -2746,7 +2746,7 @@ Author: Michael Paquier 
      
      linkend="app-psql-meta-command-bind-named">\bind_named,
      and 
-     linkend="app-psql-meta-command-close">\close.
+     linkend="app-psql-meta-command-close-prepared">\close_prepared.
      
      
 


diff --git a/src/bin/psql/command.c b/src/bin/psql/command.c

index 83e84a778411a80643e403ac1fc8b2afb1819f7e..9fcd2db832656c10ea41e60b874d74e382af456f 100644 (file)

--- a/src/bin/psql/command.c
+++ b/src/bin/psql/command.c
@@ -67,8 +67,8 @@ static backslashResult exec_command_C(PsqlScanState scan_state, bool active_bran
 static backslashResult exec_command_connect(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_cd(PsqlScanState scan_state, bool active_branch,
                                       const char *cmd);
-static backslashResult exec_command_close(PsqlScanState scan_state, bool active_branch,
-                                         const char *cmd);
+static backslashResult exec_command_close_prepared(PsqlScanState scan_state,
+                                                  bool active_branch, const char *cmd);
 static backslashResult exec_command_conninfo(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_copy(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_copyright(PsqlScanState scan_state, bool active_branch);
@@ -330,8 +330,8 @@ exec_command(const char *cmd,
        status = exec_command_connect(scan_state, active_branch);
    else if (strcmp(cmd, "cd") == 0)
        status = exec_command_cd(scan_state, active_branch, cmd);
-   else if (strcmp(cmd, "close") == 0)
-       status = exec_command_close(scan_state, active_branch, cmd);
+   else if (strcmp(cmd, "close_prepared") == 0)
+       status = exec_command_close_prepared(scan_state, active_branch, cmd);
    else if (strcmp(cmd, "conninfo") == 0)
        status = exec_command_conninfo(scan_state, active_branch);
    else if (pg_strcasecmp(cmd, "copy") == 0)
@@ -728,10 +728,10 @@ exec_command_cd(PsqlScanState scan_state, bool active_branch, const char *cmd)
 }
 
 /*
- * \close -- close a previously prepared statement
+ * \close_prepared -- close a previously prepared statement
  */
 static backslashResult
-exec_command_close(PsqlScanState scan_state, bool active_branch, const char *cmd)
+exec_command_close_prepared(PsqlScanState scan_state, bool active_branch, const char *cmd)
 {
    backslashResult status = PSQL_CMD_SKIP_LINE;
 


diff --git a/src/bin/psql/common.c b/src/bin/psql/common.c

index b53cd8ab698807ecc4d156e1d4eb7191ce9ea83f..d2c0a49c46c0478dc5f7fd76f5ef6e549caf5dc0 100644 (file)

--- a/src/bin/psql/common.c
+++ b/src/bin/psql/common.c
@@ -2628,7 +2628,7 @@ clean_extended_state(void)
 
    switch (pset.send_mode)
    {
-       case PSQL_SEND_EXTENDED_CLOSE:  /* \close */
+       case PSQL_SEND_EXTENDED_CLOSE:  /* \close_prepared */
            free(pset.stmtName);
            break;
        case PSQL_SEND_EXTENDED_PARSE:  /* \parse */


diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c

index db6adec8b692be75a1c6aa0f61bc70bd5f636515..a2e009ab9bea79e03f0a5e13b7ad9f55ddd737c9 100644 (file)

--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -331,7 +331,8 @@ slashUsage(unsigned short int pager)
    HELP0("  \\bind [PARAM]...       set query parameters\n");
    HELP0("  \\bind_named STMT_NAME [PARAM]...\n"
          "                         set query parameters for an existing prepared statement\n");
-   HELP0("  \\close STMT_NAME       close an existing prepared statement\n");
+   HELP0("  \\close_prepared STMT_NAME\n"
+         "                         close an existing prepared statement\n");
    HELP0("  \\endpipeline           exit pipeline mode\n");
    HELP0("  \\flush                 flush output data to the server\n");
    HELP0("  \\flushrequest          send request to the server to flush its output buffer\n");


diff --git a/src/bin/psql/tab-complete.in.c b/src/bin/psql/tab-complete.in.c

index 2c0b4f28c14dd6a3c63c9912f23ccc2c691ae406..908eef97c6e288fca3982246e2ba04f476565742 100644 (file)

--- a/src/bin/psql/tab-complete.in.c
+++ b/src/bin/psql/tab-complete.in.c
@@ -1875,7 +1875,7 @@ psql_completion(const char *text, int start, int end)
    static const char *const backslash_commands[] = {
        "\\a",
        "\\bind", "\\bind_named",
-       "\\connect", "\\conninfo", "\\C", "\\cd", "\\close", "\\copy",
+       "\\connect", "\\conninfo", "\\C", "\\cd", "\\close_prepared", "\\copy",
        "\\copyright", "\\crosstabview",
        "\\d", "\\da", "\\dA", "\\dAc", "\\dAf", "\\dAo", "\\dAp",
        "\\db", "\\dc", "\\dconfig", "\\dC", "\\dd", "\\ddp", "\\dD",


diff --git a/src/test/regress/expected/psql.out b/src/test/regress/expected/psql.out

index cf48ae6d0c2eeeb108e679adbb5d98bfdcba7c98..236eba2540e9dc4f7d6c88cc57048da410608a4a 100644 (file)

--- a/src/test/regress/expected/psql.out
+++ b/src/test/regress/expected/psql.out
@@ -160,12 +160,12 @@ LINE 1: SELECT $1, $2
  foo4     | bar4
 (1 row)
 
--- \close (extended query protocol)
-\close
-\close: missing required argument
-\close ''
-\close stmt2
-\close stmt2
+-- \close_prepared (extended query protocol)
+\close_prepared
+\close_prepared: missing required argument
+\close_prepared ''
+\close_prepared stmt2
+\close_prepared stmt2
 SELECT name, statement FROM pg_prepared_statements ORDER BY name;
  name  |   statement    
 -------+----------------
@@ -4666,7 +4666,7 @@ bar 'bar' "bar"
    \C arg1
    \c arg1 arg2 arg3 arg4
    \cd arg1
-   \close stmt1
+   \close_prepared stmt1
    \conninfo
    \copy arg1 arg2 arg3 arg4 arg5 arg6
    \copyright


diff --git a/src/test/regress/expected/psql_pipeline.out b/src/test/regress/expected/psql_pipeline.out

index e78e6bfa0ad35483f462db5ce17e5d884bbf224e..a0816fb10b68e802de1e1a007d0656625bed73dc 100644 (file)

--- a/src/test/regress/expected/psql_pipeline.out
+++ b/src/test/regress/expected/psql_pipeline.out
@@ -564,7 +564,7 @@ SELECT $1 \bind \sendpipeline
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 ERROR:  bind message supplies 0 parameters, but prepared statement "" requires 1
@@ -572,7 +572,7 @@ ERROR:  bind message supplies 0 parameters, but prepared statement "" requires 1
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 -- Sync allows pipeline to recover.
 \syncpipeline
 \getresults
@@ -580,7 +580,7 @@ Pipeline aborted, command did not run
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
  ?column? 


diff --git a/src/test/regress/sql/psql.sql b/src/test/regress/sql/psql.sql

index 1a8a83462f022bd1fba7f96c6639e753912af7f6..e2e3124543978c21697202b45ac34c05fc99cfbb 100644 (file)

--- a/src/test/regress/sql/psql.sql
+++ b/src/test/regress/sql/psql.sql
@@ -68,11 +68,11 @@ SELECT $1, $2 \parse stmt3
 -- Multiple \g calls mean multiple executions
 \bind_named stmt2 'foo3' \g \bind_named stmt3 'foo4' 'bar4' \g
 
--- \close (extended query protocol)
-\close
-\close ''
-\close stmt2
-\close stmt2
+-- \close_prepared (extended query protocol)
+\close_prepared
+\close_prepared ''
+\close_prepared stmt2
+\close_prepared stmt2
 SELECT name, statement FROM pg_prepared_statements ORDER BY name;
 
 -- \bind (extended query protocol)
@@ -1035,7 +1035,7 @@ select \if false \\ (bogus \else \\ 42 \endif \\ forty_two;
    \C arg1
    \c arg1 arg2 arg3 arg4
    \cd arg1
-   \close stmt1
+   \close_prepared stmt1
    \conninfo
    \copy arg1 arg2 arg3 arg4 arg5 arg6
    \copyright


diff --git a/src/test/regress/sql/psql_pipeline.sql b/src/test/regress/sql/psql_pipeline.sql

index 5945eca1ef76c2f9897a4d03031e27fa1fb599e6..6788dceee2e9080ed0b454d7e8c9d054c33d55c2 100644 (file)

--- a/src/test/regress/sql/psql_pipeline.sql
+++ b/src/test/regress/sql/psql_pipeline.sql
@@ -306,21 +306,21 @@ SELECT $1 \bind \sendpipeline
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 -- Pipeline is aborted.
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 -- Sync allows pipeline to recover.
 \syncpipeline
 \getresults
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 \endpipeline

diff --git a/src/bin/psql/command.c b/src/bin/psql/command.c
index 83e84a778411a80643e403ac1fc8b2afb1819f7e..9fcd2db832656c10ea41e60b874d74e382af456f 100644 (file)
--- a/src/bin/psql/command.c
+++ b/src/bin/psql/command.c
@@ -67,8 +67,8 @@ static backslashResult exec_command_C(PsqlScanState scan_state, bool active_bran
 static backslashResult exec_command_connect(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_cd(PsqlScanState scan_state, bool active_branch,
                                       const char *cmd);
-static backslashResult exec_command_close(PsqlScanState scan_state, bool active_branch,
-                                         const char *cmd);
+static backslashResult exec_command_close_prepared(PsqlScanState scan_state,
+                                                  bool active_branch, const char *cmd);
 static backslashResult exec_command_conninfo(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_copy(PsqlScanState scan_state, bool active_branch);
 static backslashResult exec_command_copyright(PsqlScanState scan_state, bool active_branch);
@@ -330,8 +330,8 @@ exec_command(const char *cmd,
        status = exec_command_connect(scan_state, active_branch);
    else if (strcmp(cmd, "cd") == 0)
        status = exec_command_cd(scan_state, active_branch, cmd);
-   else if (strcmp(cmd, "close") == 0)
-       status = exec_command_close(scan_state, active_branch, cmd);
+   else if (strcmp(cmd, "close_prepared") == 0)
+       status = exec_command_close_prepared(scan_state, active_branch, cmd);
    else if (strcmp(cmd, "conninfo") == 0)
        status = exec_command_conninfo(scan_state, active_branch);
    else if (pg_strcasecmp(cmd, "copy") == 0)
@@ -728,10 +728,10 @@ exec_command_cd(PsqlScanState scan_state, bool active_branch, const char *cmd)
 }
 
 /*
- * \close -- close a previously prepared statement
+ * \close_prepared -- close a previously prepared statement
  */
 static backslashResult
-exec_command_close(PsqlScanState scan_state, bool active_branch, const char *cmd)
+exec_command_close_prepared(PsqlScanState scan_state, bool active_branch, const char *cmd)
 {
    backslashResult status = PSQL_CMD_SKIP_LINE;
 

diff --git a/src/bin/psql/common.c b/src/bin/psql/common.c
index b53cd8ab698807ecc4d156e1d4eb7191ce9ea83f..d2c0a49c46c0478dc5f7fd76f5ef6e549caf5dc0 100644 (file)
--- a/src/bin/psql/common.c
+++ b/src/bin/psql/common.c
@@ -2628,7 +2628,7 @@ clean_extended_state(void)
 
    switch (pset.send_mode)
    {
-       case PSQL_SEND_EXTENDED_CLOSE:  /* \close */
+       case PSQL_SEND_EXTENDED_CLOSE:  /* \close_prepared */
            free(pset.stmtName);
            break;
        case PSQL_SEND_EXTENDED_PARSE:  /* \parse */

diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index db6adec8b692be75a1c6aa0f61bc70bd5f636515..a2e009ab9bea79e03f0a5e13b7ad9f55ddd737c9 100644 (file)
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -331,7 +331,8 @@ slashUsage(unsigned short int pager)
    HELP0("  \\bind [PARAM]...       set query parameters\n");
    HELP0("  \\bind_named STMT_NAME [PARAM]...\n"
          "                         set query parameters for an existing prepared statement\n");
-   HELP0("  \\close STMT_NAME       close an existing prepared statement\n");
+   HELP0("  \\close_prepared STMT_NAME\n"
+         "                         close an existing prepared statement\n");
    HELP0("  \\endpipeline           exit pipeline mode\n");
    HELP0("  \\flush                 flush output data to the server\n");
    HELP0("  \\flushrequest          send request to the server to flush its output buffer\n");

diff --git a/src/bin/psql/tab-complete.in.c b/src/bin/psql/tab-complete.in.c
index 2c0b4f28c14dd6a3c63c9912f23ccc2c691ae406..908eef97c6e288fca3982246e2ba04f476565742 100644 (file)
--- a/src/bin/psql/tab-complete.in.c
+++ b/src/bin/psql/tab-complete.in.c
@@ -1875,7 +1875,7 @@ psql_completion(const char *text, int start, int end)
    static const char *const backslash_commands[] = {
        "\\a",
        "\\bind", "\\bind_named",
-       "\\connect", "\\conninfo", "\\C", "\\cd", "\\close", "\\copy",
+       "\\connect", "\\conninfo", "\\C", "\\cd", "\\close_prepared", "\\copy",
        "\\copyright", "\\crosstabview",
        "\\d", "\\da", "\\dA", "\\dAc", "\\dAf", "\\dAo", "\\dAp",
        "\\db", "\\dc", "\\dconfig", "\\dC", "\\dd", "\\ddp", "\\dD",

diff --git a/src/test/regress/expected/psql.out b/src/test/regress/expected/psql.out
index cf48ae6d0c2eeeb108e679adbb5d98bfdcba7c98..236eba2540e9dc4f7d6c88cc57048da410608a4a 100644 (file)
--- a/src/test/regress/expected/psql.out
+++ b/src/test/regress/expected/psql.out
@@ -160,12 +160,12 @@ LINE 1: SELECT $1, $2
  foo4     | bar4
 (1 row)
 
--- \close (extended query protocol)
-\close
-\close: missing required argument
-\close ''
-\close stmt2
-\close stmt2
+-- \close_prepared (extended query protocol)
+\close_prepared
+\close_prepared: missing required argument
+\close_prepared ''
+\close_prepared stmt2
+\close_prepared stmt2
 SELECT name, statement FROM pg_prepared_statements ORDER BY name;
  name  |   statement    
 -------+----------------
@@ -4666,7 +4666,7 @@ bar 'bar' "bar"
    \C arg1
    \c arg1 arg2 arg3 arg4
    \cd arg1
-   \close stmt1
+   \close_prepared stmt1
    \conninfo
    \copy arg1 arg2 arg3 arg4 arg5 arg6
    \copyright

diff --git a/src/test/regress/expected/psql_pipeline.out b/src/test/regress/expected/psql_pipeline.out
index e78e6bfa0ad35483f462db5ce17e5d884bbf224e..a0816fb10b68e802de1e1a007d0656625bed73dc 100644 (file)
--- a/src/test/regress/expected/psql_pipeline.out
+++ b/src/test/regress/expected/psql_pipeline.out
@@ -564,7 +564,7 @@ SELECT $1 \bind \sendpipeline
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 ERROR:  bind message supplies 0 parameters, but prepared statement "" requires 1
@@ -572,7 +572,7 @@ ERROR:  bind message supplies 0 parameters, but prepared statement "" requires 1
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 -- Sync allows pipeline to recover.
 \syncpipeline
 \getresults
@@ -580,7 +580,7 @@ Pipeline aborted, command did not run
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
  ?column? 

diff --git a/src/test/regress/sql/psql.sql b/src/test/regress/sql/psql.sql
index 1a8a83462f022bd1fba7f96c6639e753912af7f6..e2e3124543978c21697202b45ac34c05fc99cfbb 100644 (file)
--- a/src/test/regress/sql/psql.sql
+++ b/src/test/regress/sql/psql.sql
@@ -68,11 +68,11 @@ SELECT $1, $2 \parse stmt3
 -- Multiple \g calls mean multiple executions
 \bind_named stmt2 'foo3' \g \bind_named stmt3 'foo4' 'bar4' \g
 
--- \close (extended query protocol)
-\close
-\close ''
-\close stmt2
-\close stmt2
+-- \close_prepared (extended query protocol)
+\close_prepared
+\close_prepared ''
+\close_prepared stmt2
+\close_prepared stmt2
 SELECT name, statement FROM pg_prepared_statements ORDER BY name;
 
 -- \bind (extended query protocol)
@@ -1035,7 +1035,7 @@ select \if false \\ (bogus \else \\ 42 \endif \\ forty_two;
    \C arg1
    \c arg1 arg2 arg3 arg4
    \cd arg1
-   \close stmt1
+   \close_prepared stmt1
    \conninfo
    \copy arg1 arg2 arg3 arg4 arg5 arg6
    \copyright

diff --git a/src/test/regress/sql/psql_pipeline.sql b/src/test/regress/sql/psql_pipeline.sql
index 5945eca1ef76c2f9897a4d03031e27fa1fb599e6..6788dceee2e9080ed0b454d7e8c9d054c33d55c2 100644 (file)
--- a/src/test/regress/sql/psql_pipeline.sql
+++ b/src/test/regress/sql/psql_pipeline.sql
@@ -306,21 +306,21 @@ SELECT $1 \bind \sendpipeline
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 -- Pipeline is aborted.
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 -- Sync allows pipeline to recover.
 \syncpipeline
 \getresults
 SELECT $1 \bind 1 \sendpipeline
 SELECT $1 \parse a
 \bind_named a 1 \sendpipeline
-\close a
+\close_prepared a
 \flushrequest
 \getresults
 \endpipeline