From d55322b0da60a8798ffdb8b78ef90db0fb5be18e Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Thu, 22 Aug 2024 16:25:57 +0900 Subject: psql: Add more meta-commands able to use the extended protocol Currently, only unnamed prepared statement are supported by psql with the meta-command \bind. With only this command, it is not possible to test named statement creation, execution or close through the extended protocol. This commit introduces three additional commands: * \parse creates a prepared statement using the extended protocol, acting as a wrapper of libpq's PQsendPrepare(). * \bind_named binds and executes an existing prepared statement using the extended protocol, for PQsendQueryPrepared(). * \close closes an existing prepared statement using the extended protocol, for PQsendClosePrepared(). This is going to be useful to add regression tests for the extended query protocol, and I have some plans for that on separate threads. Note that \bind relies on PQsendQueryParams(). The code of psql is refactored so as bind_flag is replaced by an enum in _psqlSettings that tracks the type of libpq routine to execute, based on the meta-command involved, with the default being PQsendQuery(). This refactoring piece has been written by me, while Anthonin has implemented the rest. Author: Anthonin Bonnefoy, Michael Paquier Reviewed-by: Aleksander Alekseev, Jelte Fennema-Nio Discussion: https://postgr.es/m/CAO6_XqpSq0Q0kQcVLCbtagY94V2GxNP3zCnR6WnOM8WqXPK4nw@mail.gmail.com --- doc/src/sgml/ref/psql-ref.sgml | 90 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 07419a3b92e..3fd9959ed16 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -917,6 +917,36 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g + + \bind_named statement_name [ parameter ] ... + + + + \bind_named is equivalent to \bind, + except that it takes the name of an existing prepared statement as + first parameter. An empty string denotes the unnamed prepared + statement. + + + + Example: + +INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1 +\bind_named stmt1 'first value' 'second value' \g + + + + + This command causes the extended query protocol (see + ) to be used, unlike normal + psql operation, which uses the simple + query protocol. So this command can be useful to test the extended + query protocol from psql. + + + + + \c or \connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] @@ -1038,6 +1068,35 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g + + \close prepared_statement_name + + + + Closes the specified prepared statement. An empty string denotes the + unnamed prepared statement. If no prepared statement exists with this + name, the operation is a no-op. + + + + Example: + +SELECT $1 \parse stmt1 +\close stmt1 + + + + + This command causes the extended query protocol to be used, + unlike normal psql operation, which + uses the simple query protocol. So this command can be useful + to test the extended query protocol from + psql. + + + + + \copy { table [ ( column_list ) ] } from @@ -2780,6 +2839,37 @@ lo_import 152801 + + \parse statement_name + + + Creates a prepared statement from the current query buffer, based on + the name of a destination prepared-statement object. An empty string + denotes the unnamed prepared statement. + + + + Example: + +SELECT $1 \parse stmt1 + + + + + This command causes the extended query protocol to be used, unlike + normal psql operation, which uses the + simple query protocol. A + + message will be issued by this command so it can be useful to + test the extended query protocol from + psql. This command affects only the next + query executed; all subsequent queries will use the simple query + protocol by default. + + + + + \password [ username ] -- cgit v1.2.3