From 762c7f0fa6a5bbe79eaf9700c630e120e8d68d4f Mon Sep 17 00:00:00 2001 From: Dave Cramer Date: Tue, 3 Mar 2026 09:16:59 -0500 Subject: [PATCH 2/2] Add _pq_.holdable_portal protocol option for holdable cursors Implement support for creating holdable portals via the extended query protocol using a new protocol option instead of bumping the protocol version. This allows clients to opt-in to sending cursor options in Bind messages. Protocol Option: _pq_.holdable_portal=true When enabled, clients can include an optional Int32 cursor options field at the end of Bind messages. The CURSOR_OPT_HOLD bit (0x0020) creates a holdable portal that survives transaction commit. Benefits: - Backward compatible with protocol 3.2 - Opt-in feature via connection parameter - Uses standard _pq_. protocol option mechanism - Server can negotiate support via NegotiateProtocolVersion Backend Changes: - Add holdable_portal_enabled flag to Port structure - Parse _pq_.holdable_portal in startup packet (backend_startup.c) - Check option flag instead of protocol version in exec_bind_message() - Read cursor options from Bind message only when enabled Client (libpq) Changes: - Add holdable_portal connection parameter (default "0") - Add holdable_portal_enabled flag to PGconn structure - Send _pq_.holdable_portal=true in startup packet when enabled - Include cursor options in Bind message when enabled - Update PQsendQueryPreparedWithCursorOptions() and PQsendBindWithCursorOptions() to use option flag Documentation: - Document _pq_.holdable_portal in protocol options table - Describe cursor options field in Bind message format - Explain holdable portal lifecycle and behavior Usage: conn = PQconnectdb("dbname=postgres holdable_portal=1"); PQsendQueryPreparedWithCursorOptions(conn, stmtName, ..., 0x0020); This replaces the previous approach of using protocol version 3.3. --- doc/src/sgml/protocol.sgml | 42 ++++++++++++++++------------- src/backend/tcop/backend_startup.c | 21 ++++++++++++--- src/backend/tcop/postgres.c | 5 ++-- src/include/libpq/libpq-be.h | 1 + src/include/libpq/pqcomm.h | 2 +- src/interfaces/libpq/fe-connect.c | 4 +++ src/interfaces/libpq/fe-exec.c | 8 +++--- src/interfaces/libpq/fe-protocol3.c | 7 +++++ src/interfaces/libpq/libpq-int.h | 2 ++ 9 files changed, 62 insertions(+), 30 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index fc2b28af2b5..6e980fb1d51 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -18,7 +18,7 @@ - This document describes version 3.3 of the protocol, introduced in + This document describes version 3.2 of the protocol, introduced in PostgreSQL version 18. The server and the libpq client library are backwards compatible with protocol version 3.0, implemented in PostgreSQL 7.4 and later. @@ -192,7 +192,7 @@ Protocol Versions - The current, latest version of the protocol is version 3.3. However, for + The current, latest version of the protocol is version 3.2. However, for backwards compatibility with old server versions and middleware that don't support the version negotiation yet, libpq still uses protocol version 3.0 by default. @@ -217,7 +217,7 @@ this would occur if the client requested protocol version 4.0, which does not exist as of this writing). If the minor version requested by the client is not supported by the server (e.g., the client requests version - 3.3, but the server supports only 3.0), the server may either reject the + 3.2, but the server supports only 3.0), the server may either reject the connection or may respond with a NegotiateProtocolVersion message containing the highest minor protocol version which it supports. The client may then choose either to continue with the connection using the @@ -251,18 +251,10 @@ - - 3.3 - PostgreSQL 18 and later - Current latest version. The Bind message now supports an optional - cursor options field to control portal behavior, including the ability - to create holdable portals that survive transaction commit. - - 3.2 PostgreSQL 18 and later - The secret key used in query + Current latest version. The secret key used in query cancellation was enlarged from 4 bytes to a variable length field. The BackendKeyData message was changed to accommodate that, and the CancelRequest message was redefined to have a variable length payload. @@ -374,6 +366,16 @@ + + _pq_.holdable_portal + Enables support for cursor options in the Bind message. + When set to true, the client may include an + optional cursor options field in Bind messages to control portal + behavior, such as creating holdable portals that survive transaction + commit. See for details. + + + _pq_.[name] Any other parameter names beginning with _pq_., @@ -1109,9 +1111,9 @@ SELCT 1/0; pass NULL values for them in the Bind message.) Bind also specifies the format to use for any data returned by the query; the format can be specified overall, or per-column. - In protocol 3.3 and later, Bind can optionally specify cursor options - to control portal behavior, such as creating a holdable portal that - survives transaction commit. + If the _pq_.holdable_portal protocol option is enabled, + Bind can optionally include cursor options to control portal behavior, + such as creating a holdable portal that survives transaction commit. The response is either BindComplete or ErrorResponse. @@ -1136,8 +1138,9 @@ SELCT 1/0; If successfully created, a named portal object lasts till the end of the - current transaction, unless explicitly destroyed. However, a portal - created with the CURSOR_OPT_HOLD option (protocol 3.3 and later) is + current transaction, unless explicitly destroyed. However, if the + _pq_.holdable_portal protocol option is enabled and + the portal is created with the CURSOR_OPT_HOLD option, the portal becomes holdable and survives transaction commit, remaining valid until explicitly closed or the session ends. An unnamed portal is destroyed at the end of the transaction, or as soon as the next Bind @@ -4430,8 +4433,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" Int32 - Cursor options (protocol 3.3 and later). A bitmask of options - for the portal being created. Currently defined bits are: + Cursor options (optional, only if _pq_.holdable_portal + is enabled). A bitmask of options for the portal being created. + Currently defined bits are: 0x0001 (CURSOR_OPT_BINARY, same as setting result format codes to binary), 0x0020 (CURSOR_OPT_HOLD, creates a holdable diff --git a/src/backend/tcop/backend_startup.c b/src/backend/tcop/backend_startup.c index c517115927c..055bee287f5 100644 --- a/src/backend/tcop/backend_startup.c +++ b/src/backend/tcop/backend_startup.c @@ -779,11 +779,24 @@ ProcessStartupPacket(Port *port, bool ssl_done, bool gss_done) { /* * Any option beginning with _pq_. is reserved for use as a - * protocol-level option, but at present no such options are - * defined. + * protocol-level option. */ - unrecognized_protocol_options = - lappend(unrecognized_protocol_options, pstrdup(nameptr)); + if (strcmp(nameptr, "_pq_.holdable_portal") == 0) + { + /* Enable holdable portal support via Bind message */ + if (!parse_bool(valptr, &port->holdable_portal_enabled)) + ereport(FATAL, + (errcode(ERRCODE_INVALID_PARAMETER_VALUE), + errmsg("invalid value for parameter \"%s\": \"%s\"", + "_pq_.holdable_portal", + valptr))); + } + else + { + /* Unrecognized protocol option */ + unrecognized_protocol_options = + lappend(unrecognized_protocol_options, pstrdup(nameptr)); + } } else { diff --git a/src/backend/tcop/postgres.c b/src/backend/tcop/postgres.c index 10bb898e612..4e4de82214b 100644 --- a/src/backend/tcop/postgres.c +++ b/src/backend/tcop/postgres.c @@ -2010,8 +2010,9 @@ exec_bind_message(StringInfo input_message) rformats[i] = pq_getmsgint(input_message, 2); } - /* Get cursor options if present (protocol 3.3+) */ - if (input_message->cursor < input_message->len) + /* Get cursor options if present (_pq_.holdable_portal enabled) */ + if (MyProcPort->holdable_portal_enabled && + input_message->cursor < input_message->len) { cursorOptions = pq_getmsgint(input_message, 4); elog(DEBUG1, "exec_bind_message: read cursorOptions=0x%04x from message", cursorOptions); diff --git a/src/include/libpq/libpq-be.h b/src/include/libpq/libpq-be.h index 921b2daa4ff..1c11d706edd 100644 --- a/src/include/libpq/libpq-be.h +++ b/src/include/libpq/libpq-be.h @@ -151,6 +151,7 @@ typedef struct Port char *user_name; char *cmdline_options; List *guc_options; + bool holdable_portal_enabled; /* _pq_.holdable_portal option */ /* * The startup packet application name, only used here for the "connection diff --git a/src/include/libpq/pqcomm.h b/src/include/libpq/pqcomm.h index 28e7944cdf4..a29c9c94d79 100644 --- a/src/include/libpq/pqcomm.h +++ b/src/include/libpq/pqcomm.h @@ -92,7 +92,7 @@ is_unixsock_path(const char *path) * The earliest and latest frontend/backend protocol version supported. */ #define PG_PROTOCOL_EARLIEST PG_PROTOCOL(3,0) -#define PG_PROTOCOL_LATEST PG_PROTOCOL(3,3) +#define PG_PROTOCOL_LATEST PG_PROTOCOL(3,2) /* * Reserved protocol numbers, which have special semantics: diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c index 67fa83ca159..a0622820d7e 100644 --- a/src/interfaces/libpq/fe-connect.c +++ b/src/interfaces/libpq/fe-connect.c @@ -417,6 +417,10 @@ static const internalPQconninfoOption PQconninfoOptions[] = { "SSL-Key-Log-File", "D", 64, offsetof(struct pg_conn, sslkeylogfile)}, + {"holdable_portal", NULL, "0", NULL, + "Holdable-Portal", "", 1, + offsetof(struct pg_conn, holdable_portal)}, + /* Terminating entry --- MUST BE LAST */ {NULL, NULL, NULL, NULL, NULL, NULL, 0} diff --git a/src/interfaces/libpq/fe-exec.c b/src/interfaces/libpq/fe-exec.c index 6f85382819f..9facb606f20 100644 --- a/src/interfaces/libpq/fe-exec.c +++ b/src/interfaces/libpq/fe-exec.c @@ -1750,8 +1750,8 @@ PQsendQueryPreparedWithCursorOptions(PGconn *conn, pqPutInt(resultFormat, 2, conn) < 0) goto sendFailed; - /* Send cursor options if protocol 3.3+ */ - if (conn->pversion >= PG_PROTOCOL(3, 3)) + /* Send cursor options if _pq_.holdable_portal enabled */ + if (conn->holdable_portal_enabled) { if (pqPutInt(cursorOptions, 4, conn) < 0) goto sendFailed; @@ -1866,8 +1866,8 @@ PQsendBindWithCursorOptions(PGconn *conn, pqPutInt(resultFormat, 2, conn) < 0) goto sendFailed; - /* Send cursor options if protocol 3.3+ */ - if (conn->pversion >= PG_PROTOCOL(3, 3)) + /* Send cursor options if _pq_.holdable_portal enabled */ + if (conn->holdable_portal_enabled) { if (pqPutInt(cursorOptions, 4, conn) < 0) goto sendFailed; diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c index 8c1fda5caf0..b64a23048ef 100644 --- a/src/interfaces/libpq/fe-protocol3.c +++ b/src/interfaces/libpq/fe-protocol3.c @@ -2521,6 +2521,13 @@ build_startup_packet(const PGconn *conn, char *packet, if (conn->pversion == PG_PROTOCOL_GREASE) ADD_STARTUP_OPTION("_pq_.test_protocol_negotiation", ""); + /* Add _pq_.holdable_portal option if enabled */ + if (conn->holdable_portal && conn->holdable_portal[0] == '1') + { + ADD_STARTUP_OPTION("_pq_.holdable_portal", "true"); + conn->holdable_portal_enabled = true; + } + /* Add any environment-driven GUC settings needed */ for (next_eo = options; next_eo->envName; next_eo++) { diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h index bd7eb59f5f8..7fdd92f2044 100644 --- a/src/interfaces/libpq/libpq-int.h +++ b/src/interfaces/libpq/libpq-int.h @@ -430,6 +430,7 @@ struct pg_conn char *scram_client_key; /* base64-encoded SCRAM client key */ char *scram_server_key; /* base64-encoded SCRAM server key */ char *sslkeylogfile; /* where should the client write ssl keylogs */ + char *holdable_portal; /* enable _pq_.holdable_portal option */ bool cancelRequest; /* true if this connection is used to send a * cancel request, instead of being a normal @@ -504,6 +505,7 @@ struct pg_conn int sversion; /* server version, e.g. 70401 for 7.4.1 */ bool pversion_negotiated; /* true if NegotiateProtocolVersion * was received */ + bool holdable_portal_enabled; /* _pq_.holdable_portal option */ bool auth_req_received; /* true if any type of auth req received */ bool password_needed; /* true if server demanded a password */ bool gssapi_used; /* true if authenticated via gssapi */ -- 2.50.1 (Apple Git-155)