From e3d37853ecd51c87976df7ea5c5d641f45668370 Mon Sep 17 00:00:00 2001 From: Jacob Champion Date: Fri, 6 Feb 2026 10:25:12 -0800 Subject: [PATCH] doc: Expand upon protocol versions and extensions First, split the Protocol Versions table in two, and lead with the list of versions that are supported today. Reserved and unsupported version numbers go into the second table. Second, in anticipation of a new (reserved) protocol extension, document the extension negotiation process alongside version negotiation, and add the corresponding tables for future extension parameter registrations. Reviewed-by: Jelte Fennema-Nio Reviewed-by: David G. Johnston Discussion: https://postgr.es/m/DDPR5BPWH1RJ.1LWAK6QAURVAY%40jeltef.nl --- doc/src/sgml/protocol.sgml | 108 +++++++++++++++++++++++++++++++++---- 1 file changed, 98 insertions(+), 10 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index a2b528c481e..36fd327d4b9 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -223,10 +223,12 @@ shows the currently supported protocol versions. + + documents protocol versions that are unsupported or otherwise reserved. - Protocol Versions + Supported Protocol Versions @@ -247,6 +249,27 @@ message was redefined to have a variable length payload. + + 3.0 + PostgreSQL 7.4 and later + + + +
+ + + Other Protocol Versions + + + + + Version + Supported by + Description + + + + 3.1 - @@ -257,15 +280,78 @@ - 3.0 - PostgreSQL 7.4 and later - - 2.0 up to PostgreSQL 13 - See previous releases of + Obsolete. See previous releases of the PostgreSQL documentation for - details + details. + + + +
+ + + + Protocol Extensions + + + Servers and clients may additionally negotiate individual extensions to the + protocol version in use. These are offered by the client in the startup + message, as specially-named parameters with a _pq_. + prefix. Servers reject any unknown or unsupported extensions by sending a + NegotiateProtocolVersion message containing the list of rejected parameter + names, at which point the client may choose whether to continue with the + connection. and + document the supported + and reserved protocol extension parameters, respectively. + + + + Supported Protocol Extensions + + + + + + + Parameter Name + Values + Supported by + Description + + + + + + + (No supported protocol extensions are currently defined.) + + + + +
+ + + Reserved Protocol Extensions + + + + + Parameter Name + Description + + + + + + _pq_.[name] + Any other parameter names beginning with _pq_., + that are not defined above, are reserved for future protocol expansion. + Servers must reject any that are received from a + client, by sending a NegotiateProtocolVersion message during the + startup flow, and should + otherwise continue the connection. + @@ -295,8 +381,8 @@ To begin a session, a frontend opens a connection to the server and sends a startup message. This message includes the names of the user and of the database the user wants to connect to; it also identifies the particular - protocol version to be used. (Optionally, the startup message can include - additional settings for run-time parameters.) + protocol version to be used. (Optionally, the startup message can request + protocol extensions and include additional settings for run-time parameters.) The server then uses this information and the contents of its configuration files (such as pg_hba.conf) to determine @@ -6151,7 +6237,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" In addition to the above, other parameters may be listed. Parameter names beginning with _pq_. are - reserved for use as protocol extensions, while others are + reserved for use as + protocol extensions, + while others are treated as run-time parameters to be set at backend start time. Such settings will be applied during backend start (after parsing the command-line arguments if any) and will -- 2.47.3