docs: Update Protocol Changes checklist page for protocol 3.2

JelteF · Commitfest Bot · commit 8099bbc24537 · 2025-08-04T15:36:20.000Z
The docs already contained a page with protocol changes made by the
introduction of protocol version 3.0 (introduced in Postgres 7.4). This
commit adds the changes to this list which are introduced by protocol
version 3.2 (introduced in Postgres 18). It also adds protocol changes
that were done during the lifetime of protocol version 3.0 but which
did not receive an associated version bump.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
@@ -7880,106 +7880,160 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
  </sect1>
 
  <sect1 id="protocol-changes">
-  <title>Summary of Changes since Protocol 2.0</title>
+  <title>Summary of Protocol Changes</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.
+   developers trying to update existing client libraries to the most recent
+   protocol version.
   </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>
+  <sect2 id="protocol-changes-3.2">
+   <title>Protocol changes introduced in version 3.2</title>
 
-  <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>
+    Protocol version 3.2 was introduced in <productname>PostgreSQL</productname> 18.
+   </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 BackendKeyData and CancelRequest messages were changed to allow a
+    variable size for the secret key instead of the 32-bit fixed size the
+    secret had before. The maximum size of the secret is now 256 bytes.
+   </para>
+  </sect2>
 
-  <para>
-   The ReadyForQuery ('<literal>Z</literal>') message includes a transaction status
-   indicator.
-  </para>
+  <sect2 id="protocol-changes-3.0-no-bump">
+   <title>Protocol changes introduced in version 3.0 without a protocol version bump</title>
 
-  <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>
+    During the lifetime of protocol version 3.0 some changes to this protocol
+    version were made without bumping the protocol version. These changes are
+    listed below.
+   </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>
+    In <productname>PostgreSQL</productname> 9.3.21 the
+    NegotiateProtocolVersion message was introduced. This allows servers to
+    indicate to the client that it does not support the protocol version that
+    was requested by the client and that it wants to downgrade to a lower one.
+   </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>
+    In <productname>PostgreSQL</productname> 17 SSL negotiation was modified.
+    Before version 17 To initiate an SSL-encrypted connection, the frontend initially
+    sends an SSLRequest message rather than a StartupMessage. The server then responds
+    with a single byte containing S or N, indicating that it is willing or unwilling
+    to perform SSL, respectively. After which the frontend begins SSL negotiation
+    Starting in version 17 the server will also recognize connections which
+    immediately begin SSL negotiation without any previous SSLRequest packets
+   </para>
+  </sect2>
 
-  <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>
+  <sect2 id="protocol-changes-3.0">
+   <title>Protocol changes introduced in version 3.0</title>
 
-  <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>
+    Protocol version 3.0 was introduced in
+    <productname>PostgreSQL</productname> 7.4. It introduced many changes
+    compared to the previous 2.0 protocol version. These changes are listed
+    below, although mostly for historical reasons, since protocol version 2.0
+    has not been supported by servers and clients for quite a long time.
+   </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 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>
-   The CursorResponse ('<literal>P</literal>') message is no longer generated by
-   the backend.
-  </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>
-   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>
+    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 EmptyQueryResponse ('<literal>I</literal>') message used to include an empty
-   string parameter; this has been removed.
-  </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>
+  </sect2>
  </sect1>
 </chapter>
