From 28b5726561841556dc3e00ffe26b01a8107ee654 Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Tue, 4 Jul 2023 14:48:10 +0900 Subject: libpq: Add support for Close on portals and statements The following routines are added to libpq: PGresult *PQclosePrepared(PGconn *conn, const char *stmt); PGresult *PQclosePortal(PGconn *conn, const char *portal); int PQsendClosePrepared(PGconn *conn, const char *stmt); int PQsendClosePortal(PGconn *conn, const char *portal); The "send" routines are non-blocking versions of the two others. Close messages are part of the protocol but they did not have a libpq implementation. And, having these routines is for instance useful with connection poolers as these can detect more easily Close messages than DEALLOCATE queries. The implementation takes advantage of what the Describe routines rely on for portals and statements. Some regression tests are added in libpq_pipeline, for the four new routines, by closing portals and statements created already by the tests. Author: Jelte Fennema Reviewed-by: Jian He, Michael Paquier Discussion: https://postgr.es/m/CAGECzQTb4xFAopAVokudB+L62Kt44mNAL4Z9zZ7UTrs1TRFvWA@mail.gmail.com --- doc/src/sgml/libpq.sgml | 125 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 116 insertions(+), 9 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 2225e4e0ef3..b6f5aba1b18 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -3250,10 +3250,7 @@ PGresult *PQprepare(PGconn *conn, Prepared statements for use with can also be created by executing SQL - statements. Also, although there is no libpq - function for deleting a prepared statement, the SQL statement - can be used for that purpose. + statements. @@ -3360,6 +3357,66 @@ PGresult *PQdescribePortal(PGconn *conn, const char *portalName); + + + PQclosePreparedPQclosePrepared + + + + Submits a request to close the specified prepared statement, and waits + for completion. + +PGresult *PQclosePrepared(PGconn *conn, const char *stmtName); + + + + + allows an application to close + a previously prepared statement. Closing a statement releases all + of its associated resources on the server and allows its name to be + reused. + + + + stmtName can be "" or + NULL to reference the unnamed statement. It is fine + if no statement exists with this name, in that case the operation is a + no-op. On success, a PGresult with + status PGRES_COMMAND_OK is returned. + + + + + + PQclosePortalPQclosePortal + + + + Submits a request to close the specified portal, and waits for + completion. + +PGresult *PQclosePortal(PGconn *conn, const char *portalName); + + + + + allows an application to trigger + a close of a previously created portal. Closing a portal releases all + of its associated resources on the server and allows its name to be + reused. (libpq does not provide any + direct access to portals, but you can use this function to close a + cursor created with a DECLARE CURSOR SQL command.) + + + + portalName can be "" or + NULL to reference the unnamed portal. It is fine + if no portal exists with this name, in that case the operation is a + no-op. On success, a PGresult with status + PGRES_COMMAND_OK is returned. + + + @@ -4851,15 +4908,19 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); , , , - , and + , , + , and + , which can be used with to duplicate the functionality of , , , - , and + , + , and + respectively. @@ -5008,6 +5069,46 @@ int PQsendDescribePortal(PGconn *conn, const char *portalName); + + PQsendClosePreparedPQsendClosePrepared + + + + Submits a request to close the specified prepared statement, without + waiting for completion. + +int PQsendClosePrepared(PGconn *conn, const char *stmtName); + + + This is an asynchronous version of : + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call to + obtain the results. The function's parameters are handled + identically to . + + + + + + PQsendClosePortalPQsendClosePortal + + + + Submits a request to close specified portal, without waiting for + completion. + +int PQsendClosePortal(PGconn *conn, const char *portalName); + + + This is an asynchronous version of : + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call to + obtain the results. The function's parameters are handled + identically to . + + + + PQgetResultPQgetResult @@ -5019,7 +5120,9 @@ int PQsendDescribePortal(PGconn *conn, const char *portalName); , , , - , or + , + , + , or call, and returns it. A null pointer is returned when the command is complete and there @@ -5350,6 +5453,8 @@ int PQflush(PGconn *conn); PQexecPrepared, PQdescribePrepared, PQdescribePortal, + PQclosePrepared, + PQclosePortal, is an error condition. PQsendQuery is also disallowed, because it uses the simple query protocol. @@ -5389,8 +5494,10 @@ int PQflush(PGconn *conn); establish a synchronization point in the pipeline, or when is called. The functions , - , and - also work in pipeline mode. + , + , + , and + also work in pipeline mode. Result processing is described below. -- cgit v1.2.3