From 404247348f6328aea4206cf5252ee9dbd9794f84 Mon Sep 17 00:00:00 2001 From: Jacob Champion Date: Wed, 21 Jan 2026 14:31:47 -0800 Subject: [PATCH v5 1/3] 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 a table to contain extension parameter registrations in the future. (I considered splitting this in two as well, but then the first table would be empty for a long while, which seemed silly.) Discussion: https://postgr.es/m/DDPR5BPWH1RJ.1LWAK6QAURVAY%40jeltef.nl --- doc/src/sgml/protocol.sgml | 113 +++++++++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 11 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index a2b528c481e..792ae73b369 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -189,7 +189,7 @@ - Protocol Versions + Protocol Versions and Extensibility The current, latest version of the protocol is version 3.2. However, for @@ -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,81 @@ - 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. + + + +
+ + + Servers and clients may additionally negotiate individual extensions to the + protocol version in use. These are offered by the client as specially-named + parameters in the startup message. 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. + shows the current list of protocol extension parameters. + + + + Protocol Extensions + + + + + + + + + + + + + + + + + + + Parameter Name + Values + Supported by + Description + + + + + Defined + + + + (No supported protocol extensions are currently defined.) + + + + Reserved + + + _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 +384,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 +6240,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.34.1