On Tue, 12 Aug 2025 at 11:52, Jelte Fennema-Nio <[email protected]> wrote:
I had forgotten about that table. How about we simply remove this page completely and integrate the info about changes without a version bump into the table?
After Jacob made his changes to the "Protocol Versions" section in e3d37853ecd, now seemed a good moment to update this patch to do the proposed.
From a5160f49c812e29183718161849aec96c52da300 Mon Sep 17 00:00:00 2001 From: Jelte Fennema-Nio <[email protected]> Date: Sun, 8 Feb 2026 20:59:18 +0100 Subject: [PATCH v2 1/2] doc: Include historical protocol changes without a protocol version bump In the past two updates were made to the protocol definition without bumping the protocol version. To make these changes clearly visible to implementers of the protocol this commit starts to list them in the "Supported Protocol Versions" table. --- doc/src/sgml/protocol.sgml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 89ac680efd5..101267c097d 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -251,7 +251,29 @@ </row> <row> <entry>3.0</entry> + <entry>PostgreSQL 17 and later</entry> + <entry>The 3.0 protocol definition was updated to recognize connections that + immediately begin SSL negotiation without a prior SSLRequest message. + Clients based on libpq can use <literal>sslnegotiation=direct</literal> + to skip sending the SSLRequest. + </entry> + </row> + <row> + <entry>3.0</entry> + <entry>PostgreSQL 9.3.21 and later</entry> + <entry>The 3.0 protocol definition was updated to include a + NegotiateProtocolVersion message. The NegotiateProtocolVersion message + allows servers to indicate to the client that it does not support the + minor protocol version or protocol extensions that the client has + requested. The client can then choose to continue using the connection + with the older protocol version and/or without the unsupported protocol + extensions, or to abort the connection attempt. + </entry> + </row> + <row> + <entry>3.0</entry> <entry>PostgreSQL 7.4 and later</entry> + <entry>The first 3.x protocol version.</entry> </row> </tbody> </tgroup> base-commit: 73dd7163c5d19f93b629d1ccd9d2a2de6e9667f6 -- 2.52.0
From 6f85c536546e8d5d85d1438845676a36508085d8 Mon Sep 17 00:00:00 2001 From: Jelte Fennema-Nio <[email protected]> Date: Sun, 8 Feb 2026 21:04:57 +0100 Subject: [PATCH v2 2/2] doc: Remove "Summary of Changes since Protocol 2.0" Protocol 2.0 has not been in active use for quite some time now. So there's no need to still explain to client authors what they need to do to update to protocol version 3.0. Another option would have been to update this section to explain how to protocol version 3.2, but removing seemed more sense. We now have the "Protocol Versions" and "Protocol Extensions" sections to explain the differences between the different protocol versions that are still in use. That table also describes version 2.0 as obsolete and refers to documentation for previous releases for readers interested in that version. --- doc/src/sgml/protocol.sgml | 104 ------------------------------------- 1 file changed, 104 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 101267c097d..bee73780e81 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -7891,108 +7891,4 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" </varlistentry> </variablelist> </sect1> - - <sect1 id="protocol-changes"> - <title>Summary of Changes since Protocol 2.0</title> - - <para> - This section provides a quick checklist of changes, for the benefit of - developers trying to update existing client libraries to protocol 3.0. - </para> - - <para> - The initial startup packet uses a flexible list-of-strings format - instead of a fixed format. Notice that session default values for run-time - parameters can now be specified directly in the startup packet. (Actually, - you could do that before using the <literal>options</literal> field, but given the - limited width of <literal>options</literal> and the lack of any way to quote - whitespace in the values, it wasn't a very safe technique.) - </para> - - <para> - All messages now have a length count immediately following the message type - byte (except for startup packets, which have no type byte). Also note that - PasswordMessage now has a type byte. - </para> - - <para> - ErrorResponse and NoticeResponse ('<literal>E</literal>' and '<literal>N</literal>') - messages now contain multiple fields, from which the client code can - assemble an error message of the desired level of verbosity. Note that - individual fields will typically not end with a newline, whereas the single - string sent in the older protocol always did. - </para> - - <para> - The ReadyForQuery ('<literal>Z</literal>') message includes a transaction status - indicator. - </para> - - <para> - The distinction between BinaryRow and DataRow message types is gone; the - single DataRow message type serves for returning data in all formats. - Note that the layout of DataRow has changed to make it easier to parse. - Also, the representation of binary values has changed: it is no longer - directly tied to the server's internal representation. - </para> - - <para> - There is a new <quote>extended query</quote> sub-protocol, which adds the frontend - message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the - backend message types ParseComplete, BindComplete, PortalSuspended, - ParameterDescription, NoData, and CloseComplete. Existing clients do not - have to concern themselves with this sub-protocol, but making use of it - might allow improvements in performance or functionality. - </para> - - <para> - <command>COPY</command> data is now encapsulated into CopyData and CopyDone messages. There - is a well-defined way to recover from errors during <command>COPY</command>. The special - <quote><literal>\.</literal></quote> last line is not needed anymore, and is not sent - during <command>COPY OUT</command>. - (It is still recognized as a terminator during text-mode <command>COPY - IN</command>, but not in CSV mode. The text-mode behavior is - deprecated and may eventually be removed.) Binary <command>COPY</command> is supported. - The CopyInResponse and CopyOutResponse messages include fields indicating - the number of columns and the format of each column. - </para> - - <para> - The layout of FunctionCall and FunctionCallResponse messages has changed. - FunctionCall can now support passing NULL arguments to functions. It also - can handle passing parameters and retrieving results in either text or - binary format. There is no longer any reason to consider FunctionCall a - potential security hole, since it does not offer direct access to internal - server data representations. - </para> - - <para> - The backend sends ParameterStatus ('<literal>S</literal>') messages during connection - startup for all parameters it considers interesting to the client library. - Subsequently, a ParameterStatus message is sent whenever the active value - changes for any of these parameters. - </para> - - <para> - The RowDescription ('<literal>T</literal>') message carries new table OID and column - number fields for each column of the described row. It also shows the format - code for each column. - </para> - - <para> - The CursorResponse ('<literal>P</literal>') message is no longer generated by - the backend. - </para> - - <para> - The NotificationResponse ('<literal>A</literal>') message has an additional string - field, which can carry a <quote>payload</quote> string passed - from the <command>NOTIFY</command> event sender. - </para> - - <para> - The EmptyQueryResponse ('<literal>I</literal>') message used to include an empty - string parameter; this has been removed. - </para> - </sect1> </chapter> -- 2.52.0
