Correct documentation for protocol version
Greetings,
The current docs say that if a client asks for a protocol that the backend
doesn't support, it will return the newest minor version.
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
However that isn't what it returns. It actually returns the entire newest
protocol that it supports. Attached is a patch to fix the docs.
Dave Cramer
Attachments:
protocol.patchapplication/octet-stream; name=protocol.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..2c525bd520d 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5336,8 +5336,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ Newest major and minor version supported by the server.
+ Major is in the upper 16 bits and the lower in the low 16 bits.
</para>
</listitem>
</varlistentry>
On 2025/04/10 18:52, Dave Cramer wrote:
Greetings,
The current docs say that if a client asks for a protocol that the backend doesn't support, it will return the newest minor version. https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>
However that isn't what it returns. It actually returns the entire newest protocol that it supports. Attached is a patch to fix the docs.
As far as I read the code, the server returns the protocol version requested by
the client if it's less than or equal to the latest version the server supports.
Otherwise, it returns the latest supported version. So the proposed description
doesn't seem accurate either, does it?
+ Major is in the upper 16 bits and the lower in the low 16 bits.
To match the style of similar descriptions, how about rephrasing it as:
"The most significant 16 bits are the major version number, and the least
significant 16 bits are the minor version number”?
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Thu, 10 Apr 2025 at 09:54, Fujii Masao <masao.fujii@oss.nttdata.com>
wrote:
On 2025/04/10 18:52, Dave Cramer wrote:
Greetings,
The current docs say that if a client asks for a protocol that the
backend doesn't support, it will return the newest minor version.
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSIONHowever that isn't what it returns. It actually returns the entire
newest protocol that it supports. Attached is a patch to fix the docs.
As far as I read the code, the server returns the protocol version
requested by
the client if it's less than or equal to the latest version the server
supports.
Otherwise, it returns the latest supported version. So the proposed
description
doesn't seem accurate either, does it?
I've added a note as to when this is sent. AFAICT through testing and the
fact that the pgjdbc driver has never handled this message
I'm pretty sure it only sends this message if the requested protocol is not
equal to the protocol the server supports.
+ Major is in the upper 16 bits and the lower in the low 16 bits.
To match the style of similar descriptions, how about rephrasing it as:
"The most significant 16 bits are the major version number, and the least
significant 16 bits are the minor version number”?Done in new patch attached
Dave
Attachments:
protocol-1.patchapplication/octet-stream; name=protocol-1.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..56615b4d0a7 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5317,7 +5317,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('v')</term>
<listitem>
<para>
- Identifies the message as a protocol version negotiation
+ Identifies the message as a protocol version negotiation.
+ The server sends this message if the requested protocol is
+ not equal to the version the server supports.
message.
</para>
</listitem>
@@ -5336,8 +5338,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ Latest major and minor version supported by the server.
+ The most significant 16 bits are the major version number, and the least
+ significant 16 bits are the minor version number.
</para>
</listitem>
</varlistentry>
On Thu, Apr 10, 2025 at 7:41 AM Dave Cramer <davecramer@gmail.com> wrote:
Done in new patch attached
I think this patch splices a sentence:
+ not equal to the version the server supports.
message.
+1 for clarifying the message description; it has vaguely bothered me
for a while [1]/messages/by-id/7a43f140-60e7-87ce-cf68-ea6d40e4b904@timescale.com. :)
--Jacob
[1]: /messages/by-id/7a43f140-60e7-87ce-cf68-ea6d40e4b904@timescale.com
On 2025/04/10 23:40, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 09:54, Fujii Masao <masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/10 18:52, Dave Cramer wrote:
Greetings,
The current docs say that if a client asks for a protocol that the backend doesn't support, it will return the newest minor version. https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION> <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>>
However that isn't what it returns. It actually returns the entire newest protocol that it supports. Attached is a patch to fix the docs.
As far as I read the code, the server returns the protocol version requested by
the client if it's less than or equal to the latest version the server supports.
Otherwise, it returns the latest supported version. So the proposed description
doesn't seem accurate either, does it?I've added a note as to when this is sent. AFAICT through testing and the fact that the pgjdbc driver has never handled this message
I'm pretty sure it only sends this message if the requested protocol is not equal to the protocol the server supports.
No, the message is also sent when the client requests protocol options that
the server doesn't recognize. In that case, if the client requests an older
protocol version along with unknown options, the server responds with
the requested protocol version, not the latest one.
+ Major is in the upper 16 bits and the lower in the low 16 bits.
To match the style of similar descriptions, how about rephrasing it as:
"The most significant 16 bits are the major version number, and the least
significant 16 bits are the minor version number”?Done in new patch attached
Thanks!
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Thu, 10 Apr 2025 at 11:17, Fujii Masao <masao.fujii@oss.nttdata.com>
wrote:
On 2025/04/10 23:40, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 09:54, Fujii Masao <masao.fujii@oss.nttdata.com
<mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/10 18:52, Dave Cramer wrote:
Greetings,
The current docs say that if a client asks for a protocol that
the backend doesn't support, it will return the newest minor version.
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSIONHowever that isn't what it returns. It actually returns the
entire newest protocol that it supports. Attached is a patch to fix the
docs.As far as I read the code, the server returns the protocol version
requested by
the client if it's less than or equal to the latest version the
server supports.
Otherwise, it returns the latest supported version. So the proposed
description
doesn't seem accurate either, does it?
I've added a note as to when this is sent. AFAICT through testing and
the fact that the pgjdbc driver has never handled this message
I'm pretty sure it only sends this message if the requested protocol is
not equal to the protocol the server supports.
No, the message is also sent when the client requests protocol options that
the server doesn't recognize. In that case, if the client requests an older
protocol version along with unknown options, the server responds with
the requested protocol version, not the latest one.
OK, I hadn't contemplated the unrecognized options. However AFAICT the
documentation in the code state
/*
* If the client requested a newer protocol version or if the client
* requested any protocol options we didn't recognize, let them know
* the newest minor protocol version we do support and the names of
* any unrecognized options.
*/
and the code agrees that we send the latest protocol version that we
support, not the requested one.
Dave
Attachments:
protocol-2.patchapplication/octet-stream; name=protocol-2.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..721af948098 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5317,7 +5317,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('v')</term>
<listitem>
<para>
- Identifies the message as a protocol version negotiation
+ Identifies the message as a protocol version negotiation.
+ The server sends this message if the requested protocol is
+ not equal to the version the server supports or the client
+ requests protocol options that are not recognized.
message.
</para>
</listitem>
@@ -5336,8 +5339,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ Latest major and minor version supported by the server.
+ The most significant 16 bits are the major version number, and the least
+ significant 16 bits are the minor version number.
</para>
</listitem>
</varlistentry>
On 2025/04/11 0:49, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 11:17, Fujii Masao <masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/10 23:40, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 09:54, Fujii Masao <masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com> <mailto:masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com>>> wrote:
On 2025/04/10 18:52, Dave Cramer wrote:
> Greetings,
>
> The current docs say that if a client asks for a protocol that the backend doesn't support, it will return the newest minor version. https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION> <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>> <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION> <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>>>
>
> However that isn't what it returns. It actually returns the entire newest protocol that it supports. Attached is a patch to fix the docs.As far as I read the code, the server returns the protocol version requested by
the client if it's less than or equal to the latest version the server supports.
Otherwise, it returns the latest supported version. So the proposed description
doesn't seem accurate either, does it?I've added a note as to when this is sent. AFAICT through testing and the fact that the pgjdbc driver has never handled this message
I'm pretty sure it only sends this message if the requested protocol is not equal to the protocol the server supports.No, the message is also sent when the client requests protocol options that
the server doesn't recognize. In that case, if the client requests an older
protocol version along with unknown options, the server responds with
the requested protocol version, not the latest one.OK, I hadn't contemplated the unrecognized options. However AFAICT the documentation in the code state
/*
* If the client requested a newer protocol version or if the client
* requested any protocol options we didn't recognize, let them know
* the newest minor protocol version we do support and the names of
* any unrecognized options.
*/and the code agrees that we send the latest protocol version that we support, not the requested one.
SendNegotiateProtocolVersion() sends the NegotiateProtocolVersion message and
returns the protocol version stored in the FrontendProtocol variable:
static void
SendNegotiateProtocolVersion(List *unrecognized_protocol_options)
{
StringInfoData buf;
ListCell *lc;
pq_beginmessage(&buf, PqMsg_NegotiateProtocolVersion);
pq_sendint32(&buf, FrontendProtocol);
FrontendProtocol is set by ProcessStartupPacket() as Min(proto, PG_PROTOCOL_LATEST),
where proto is the protocol version requested by the client. So, if the client
requests an older version, i.e., proto is smaller than PG_PROTOCOL_LATEST,
the server may respond with that requested version:
/*
* Set FrontendProtocol now so that ereport() knows what format to send if
* we fail during startup. We use the protocol version requested by the
* client unless it's higher than the latest version we support. It's
* possible that error message fields might look different in newer
* protocol versions, but that's something those new clients should be
* able to deal with.
*/
FrontendProtocol = Min(proto, PG_PROTOCOL_LATEST);
Am I missing something?
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Thu, 10 Apr 2025 at 12:17, Fujii Masao <masao.fujii@oss.nttdata.com>
wrote:
On 2025/04/11 0:49, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 11:17, Fujii Masao <masao.fujii@oss.nttdata.com
<mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/10 23:40, Dave Cramer wrote:
On Thu, 10 Apr 2025 at 09:54, Fujii Masao <
masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com> <mailto:
masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com>>> wrote:On 2025/04/10 18:52, Dave Cramer wrote:
Greetings,
The current docs say that if a client asks for a protocol
that the backend doesn't support, it will return the newest minor version.
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>>
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION>
<
https://www.postgresql.org/docs/current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION <
However that isn't what it returns. It actually returns
the entire newest protocol that it supports. Attached is a patch to fix the
docs.As far as I read the code, the server returns the protocol
version requested by
the client if it's less than or equal to the latest version
the server supports.
Otherwise, it returns the latest supported version. So the
proposed description
doesn't seem accurate either, does it?
I've added a note as to when this is sent. AFAICT through testing
and the fact that the pgjdbc driver has never handled this message
I'm pretty sure it only sends this message if the requested
protocol is not equal to the protocol the server supports.
No, the message is also sent when the client requests protocol
options that
the server doesn't recognize. In that case, if the client requests
an older
protocol version along with unknown options, the server responds with
the requested protocol version, not the latest one.OK, I hadn't contemplated the unrecognized options. However AFAICT the
documentation in the code state
/*
* If the client requested a newer protocol version or if the client
* requested any protocol options we didn't recognize, let them know
* the newest minor protocol version we do support and the names of
* any unrecognized options.
*/and the code agrees that we send the latest protocol version that we
support, not the requested one.
SendNegotiateProtocolVersion() sends the NegotiateProtocolVersion message
and
returns the protocol version stored in the FrontendProtocol variable:static void
SendNegotiateProtocolVersion(List *unrecognized_protocol_options)
{
StringInfoData buf;
ListCell *lc;pq_beginmessage(&buf, PqMsg_NegotiateProtocolVersion);
pq_sendint32(&buf, FrontendProtocol);FrontendProtocol is set by ProcessStartupPacket() as Min(proto,
PG_PROTOCOL_LATEST),
where proto is the protocol version requested by the client. So, if the
client
requests an older version, i.e., proto is smaller than PG_PROTOCOL_LATEST,
the server may respond with that requested version:/*
* Set FrontendProtocol now so that ereport() knows what format to
send if
* we fail during startup. We use the protocol version requested
by the
* client unless it's higher than the latest version we support.
It's
* possible that error message fields might look different in newer
* protocol versions, but that's something those new clients
should be
* able to deal with.
*/
FrontendProtocol = Min(proto, PG_PROTOCOL_LATEST);Am I missing something?
No, you are correct.
See new patch
Dave
Attachments:
protocol-3.patchapplication/octet-stream; name=protocol-3.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..0bcece34b2a 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5317,7 +5317,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('v')</term>
<listitem>
<para>
- Identifies the message as a protocol version negotiation
+ Identifies the message as a protocol version negotiation.
+ The server sends this message if the requested protocol is
+ not equal to the version the server supports or the client
+ requests protocol options that are not recognized.
message.
</para>
</listitem>
@@ -5336,8 +5339,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ The protcol version requested by the client unless it is higher than the
+ latest version we support in which case the latest protocol version we support.
+ The most significant 16 bits are the major version number, and the least
+ significant 16 bits are the minor version number.
</para>
</listitem>
</varlistentry>
On 2025/04/11 5:17, Dave Cramer wrote:
No, you are correct.
See new patch
Thanks for updating the patch!
- Identifies the message as a protocol version negotiation
+ Identifies the message as a protocol version negotiation.
+ The server sends this message if the requested protocol is
+ not equal to the version the server supports or the client
+ requests protocol options that are not recognized.
message.You added the sentence starting with "The server sends..."
between "negotiation" and "message", but it should be placed
after "message", right?
Even though the requested version is not equal to the latest
version that the server supports, if it's older than
the latest one, the message is not sent. So how about
wording it like this instead:
-------------
Identifies the message as a protocol version negotiation message.
The server sends this message when the client requests a newer
protocol version than the server supports, or when the client
includes protocol options that the server does not recognize.
-------------
+ The protcol version requested by the client unless it is higher than the
+ latest version we support in which case the latest protocol version we support.Maybe rewording this for clarity and using “the server
instead of “we” would help. For example:
-------------
The latest protocol version supported by the server if the client
requests a newer protocol version than the server supports.
The protocol version requested by the client, otherwise.
-------------
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Fri, 11 Apr 2025 at 05:05, Fujii Masao <masao.fujii@oss.nttdata.com>
wrote:
On 2025/04/11 5:17, Dave Cramer wrote:
No, you are correct.
See new patch
Thanks for updating the patch!
- Identifies the message as a protocol version negotiation + Identifies the message as a protocol version negotiation. + The server sends this message if the requested protocol is + not equal to the version the server supports or the client + requests protocol options that are not recognized. message.You added the sentence starting with "The server sends..."
between "negotiation" and "message", but it should be placed
after "message", right?Even though the requested version is not equal to the latest
version that the server supports, if it's older than
the latest one, the message is not sent. So how about
wording it like this instead:-------------
Identifies the message as a protocol version negotiation message.
The server sends this message when the client requests a newer
protocol version than the server supports, or when the client
includes protocol options that the server does not recognize.
-------------+ The protcol version requested by the client unless it is higher than the + latest version we support in which case the latest protocol version we support.Maybe rewording this for clarity and using “the server
instead of “we” would help. For example:-------------
The latest protocol version supported by the server if the client
requests a newer protocol version than the server supports.
The protocol version requested by the client, otherwise.
-------------
Reworded as suggested
Dave
Show quoted text
Attachments:
protocol-5.patchapplication/octet-stream; name=protocol-5.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..a8e10d3970b 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5317,8 +5317,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('v')</term>
<listitem>
<para>
- Identifies the message as a protocol version negotiation
- message.
+ Identifies the message as a protocol version negotiation message.
+ The server sends this message when the client requests a newer
+ protocol version than the server supports, or when the client
+ includes protocol options that the server does not recognize.
</para>
</listitem>
</varlistentry>
@@ -5336,8 +5338,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ The latest protocol version supported by the server if the client
+ requests a newer protocol version than the server supports.
+ The protocol version requested by the client, otherwise.
+ The most significant 16 bits are the major version number, and the least
+ significant 16 bits are the minor version number.
</para>
</listitem>
</varlistentry>
On 2025/04/11 18:27, Dave Cramer wrote:
On Fri, 11 Apr 2025 at 05:05, Fujii Masao <masao.fujii@oss.nttdata.com <mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/11 5:17, Dave Cramer wrote:
No, you are correct.
See new patch
Thanks for updating the patch!
- Identifies the message as a protocol version negotiation + Identifies the message as a protocol version negotiation. + The server sends this message if the requested protocol is + not equal to the version the server supports or the client + requests protocol options that are not recognized. message.You added the sentence starting with "The server sends..."
between "negotiation" and "message", but it should be placed
after "message", right?Even though the requested version is not equal to the latest
version that the server supports, if it's older than
the latest one, the message is not sent. So how about
wording it like this instead:-------------
Identifies the message as a protocol version negotiation message.
The server sends this message when the client requests a newer
protocol version than the server supports, or when the client
includes protocol options that the server does not recognize.
-------------+ The protcol version requested by the client unless it is higher than the + latest version we support in which case the latest protocol version we support.Maybe rewording this for clarity and using “the server
instead of “we” would help. For example:-------------
The latest protocol version supported by the server if the client
requests a newer protocol version than the server supports.
The protocol version requested by the client, otherwise.
-------------Reworded as suggested
Thanks for updating the patch!
While checking the code in older branches, I noticed that the returned
protocol version is always the latest version supported by the server.
However, as we discussed, in master, the server may return the version
requested by the client. The change was introduced in commit 516b87502dc.
So, probably we'll need to update the documentation differently for
master and the older branches.
The patch adds a new explanation about when the NegotiateProtocolVersion
message is sent. But a similar explanation already exists in protocol.sgml:
<term>NegotiateProtocolVersion</term>
<listitem>
<para>
The server does not support the minor protocol version requested
by the client, but does support an earlier version of the protocol;
this message indicates the highest supported minor version. This
message will also be sent if the client requested unsupported protocol
options (i.e., beginning with <literal>_pq_.</literal>) in the
startup packet.
Given that, I'm now wondering if the new description in the patch
might be redundant.
Also, your original concern was that the phrase "Newest minor protocol version"
is inaccurate since the field contains both major and minor version numbers
(e.g., 3.2). However, based on other usage in protocol.sgml and source
comments in related code, "minor version" seems to refer to the full version
like 3.2, i.e., not just the minor part, so we might not need to reword it
after all.
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Fri, 11 Apr 2025 at 09:39, Fujii Masao <masao.fujii@oss.nttdata.com>
wrote:
On 2025/04/11 18:27, Dave Cramer wrote:
On Fri, 11 Apr 2025 at 05:05, Fujii Masao <masao.fujii@oss.nttdata.com
<mailto:masao.fujii@oss.nttdata.com>> wrote:
On 2025/04/11 5:17, Dave Cramer wrote:
No, you are correct.
See new patch
Thanks for updating the patch!
- Identifies the message as a protocol version negotiation + Identifies the message as a protocol version negotiation. + The server sends this message if the requested protocol is + not equal to the version the server supports or the client + requests protocol options that are not recognized. message.
You added the sentence starting with "The server sends..."
between "negotiation" and "message", but it should be placed
after "message", right?Even though the requested version is not equal to the latest
version that the server supports, if it's older than
the latest one, the message is not sent. So how about
wording it like this instead:-------------
Identifies the message as a protocol version negotiation message.
The server sends this message when the client requests a newer
protocol version than the server supports, or when the client
includes protocol options that the server does not recognize.
-------------+ The protcol version requested by the client unless it is
higher than the
+ latest version we support in which case the latest
protocol version we support.
Maybe rewording this for clarity and using “the server
instead of “we” would help. For example:-------------
The latest protocol version supported by the server if the client
requests a newer protocol version than the server supports.
The protocol version requested by the client, otherwise.
-------------Reworded as suggested
Thanks for updating the patch!
While checking the code in older branches, I noticed that the returned
protocol version is always the latest version supported by the server.
However, as we discussed, in master, the server may return the version
requested by the client. The change was introduced in commit 516b87502dc.
So, probably we'll need to update the documentation differently for
master and the older branches.The patch adds a new explanation about when the NegotiateProtocolVersion
message is sent. But a similar explanation already exists in protocol.sgml:<term>NegotiateProtocolVersion</term>
<listitem>
<para>
The server does not support the minor protocol version requested
by the client, but does support an earlier version of the
protocol;
this message indicates the highest supported minor version. This
message will also be sent if the client requested unsupported
protocol
options (i.e., beginning with <literal>_pq_.</literal>) in the
startup packet.
Well this isn't quite true since if you request 3.0 and have invalid
options it will return 3.0, which is not the highest supported minor
version.
Given that, I'm now wondering if the new description in the patch
might be redundant.Also, your original concern was that the phrase "Newest minor protocol
version"
is inaccurate since the field contains both major and minor version numbers
(e.g., 3.2). However, based on other usage in protocol.sgml and source
comments in related code, "minor version" seems to refer to the full
version
like 3.2, i.e., not just the minor part, so we might not need to reword it
after all.
IMO the comments should be changed to reflect reality. If 3.2 is a minor
version what is a major version ?
Dave
On Fri, 11 Apr 2025 at 21:39, Fujii Masao <masao.fujii@oss.nttdata.com> wrote:
While checking the code in older branches, I noticed that the returned
protocol version is always the latest version supported by the server.
However, as we discussed, in master, the server may return the version
requested by the client. The change was introduced in commit 516b87502dc.
So, probably we'll need to update the documentation differently for
master and the older branches.
No need for different docs. Given that older branches only support 3.0
protocol, there's no way for a client to request a version earlier
than the "latest version supported by the server".
The patch adds a new explanation about when the NegotiateProtocolVersion
message is sent. But a similar explanation already exists in protocol.sgml:
Side-comment: I think our protocol docs are pretty annoyingly spread
across two pages.
Given that, I'm now wondering if the new description in the patch
might be redundant.Also, your original concern was that the phrase "Newest minor protocol version"
is inaccurate since the field contains both major and minor version numbers
(e.g., 3.2). However, based on other usage in protocol.sgml and source
comments in related code, "minor version" seems to refer to the full version
like 3.2, i.e., not just the minor part, so we might not need to reword it
after all.
I quite like the new wording from Dave so +1 from me. I also think for
protocol docs it's especially important to be very precise and leave
very little room for interpretation.
One thing that we should probably clarify though (which was somewhat
clarified in the previous wording) is that we only send this message
if the client requested a major version that the major version that
the server supports. i.e. we will never send a
NegotiateProtocolVersion message to 3.2 if the client requested 4.0.
On Fri, 11 Apr 2025 at 22:57, Dave Cramer <davecramer@gmail.com> wrote:
Well this isn't quite true since if you request 3.0 and have invalid options it will return 3.0, which is not the highest supported minor version.
Probably good to update this section too then to be similarly correct
as your already updated section. Maybe also good to clarify further
that the version that the server responds with is the protocol version
that will be used during the following communication.
On Fri, 11 Apr 2025 at 11:02, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
On Fri, 11 Apr 2025 at 22:57, Dave Cramer <davecramer@gmail.com> wrote:
Well this isn't quite true since if you request 3.0 and have invalid
options it will return 3.0, which is not the highest supported minor
version.Probably good to update this section too then to be similarly correct
as your already updated section. Maybe also good to clarify further
that the version that the server responds with is the protocol version
that will be used during the following communication.
I've updated the wording to specify that the negotiateProtocol message will
only be sent if the client requests a major version the server supports.
Also added a note saying that this will be the protocol version that will
be used for the duration of the connectin
See attached.
Attachments:
protocol-6.patchapplication/octet-stream; name=protocol-6.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a746c967053..2212ed677ec 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -5317,8 +5317,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Byte1('v')</term>
<listitem>
<para>
- Identifies the message as a protocol version negotiation
- message.
+ Identifies the message as a protocol version negotiation message.
+ The server sends this message when the client requests a major protocol version
+ that the server supports and a newer minor protocol version than the server supports,
+ or when the client includes protocol options that the server does not recognize.
</para>
</listitem>
</varlistentry>
@@ -5336,8 +5338,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Newest minor protocol version supported by the server
- for the major protocol version requested by the client.
+ The latest protocol version supported by the server if the client
+ requests a newer protocol version than the server supports.
+ The protocol version requested by the client, otherwise.
+ The most significant 16 bits are the major version number, and the least
+ significant 16 bits are the minor version number. This will be the version
+ of the protocol which will be used for the duration of the connection.
</para>
</listitem>
</varlistentry>
On Tue, 22 Apr 2025 at 10:34, Dave Cramer <davecramer@gmail.com> wrote:
On Fri, 11 Apr 2025 at 11:02, Jelte Fennema-Nio <postgres@jeltef.nl>
wrote:On Fri, 11 Apr 2025 at 22:57, Dave Cramer <davecramer@gmail.com> wrote:
Well this isn't quite true since if you request 3.0 and have invalid
options it will return 3.0, which is not the highest supported minor
version.Probably good to update this section too then to be similarly correct
as your already updated section. Maybe also good to clarify further
that the version that the server responds with is the protocol version
that will be used during the following communication.I've updated the wording to specify that the negotiateProtocol message
will only be sent if the client requests a major version the server
supports.
Also added a note saying that this will be the protocol version that will
be used for the duration of the connectinI found another place where the docs should be updated. The Changes since
Protocol 2.0
See attached patch
Show quoted text
Attachments:
protocol-7.patchapplication/octet-stream; name=protocol-7.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index c4d3853cbf2..6ea0c1b788b 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7772,6 +7772,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<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.2.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
<para>
This section provides a quick checklist of changes, for the benefit of
developers trying to update existing client libraries to protocol 3.0.
@@ -7871,5 +7883,15 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
The EmptyQueryResponse ('<literal>I</literal>') message used to include an empty
string parameter; this has been removed.
</para>
+
+ <para>
+ In version 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 recognize connections which immediately
+ begin SSL negotiation without any previous SSLRequest packets
+ </para>
</sect1>
</chapter>
On Thu, 29 May 2025 at 00:29, Dave Cramer <davecramer@gmail.com> wrote:
I found another place where the docs should be updated. The Changes since Protocol 2.0
I think it makes sense to have a dedicated page like this that lists
any protocol changes that we do. But I think the current structure
doesn't make much sense anymore. I expect no-one to upgrade a client
from protocol 2.0 anymore. So I'd replace this page with a new one
with the following structure
# Summary of protocol changes over time
## Protocol changes in version 3.2
- Longer cancel key messages
## Protocol changes to 3.0 without protocol version bump
- NegotiateProtocolVersion in 9.?
- Direct SSL negotiation in PG17
On Thu, 29 May 2025 at 06:18, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
On Thu, 29 May 2025 at 00:29, Dave Cramer <davecramer@gmail.com> wrote:
I found another place where the docs should be updated. The Changes
since Protocol 2.0
I think it makes sense to have a dedicated page like this that lists
any protocol changes that we do. But I think the current structure
doesn't make much sense anymore. I expect no-one to upgrade a client
from protocol 2.0 anymore. So I'd replace this page with a new one
with the following structure# Summary of protocol changes over time
## Protocol changes in version 3.2
- Longer cancel key messages
## Protocol changes to 3.0 without protocol version bump
- NegotiateProtocolVersion in 9.?
- Direct SSL negotiation in PG17
Agreed that nobody upgrades a client from 2.0 but is there value in keeping
the history ?
Perhaps another section which would be "Changes in 3.x" ?
Dave
On Thu, 29 May 2025 at 13:12, Dave Cramer <davecramer@gmail.com> wrote:
Agreed that nobody upgrades a client from 2.0 but is there value in keeping the history ?
Yeah, maybe.
Perhaps another section which would be "Changes in 3.x" ?
If we decide to keep it I think it would be best to have all protocol
changes on a single page. I'd just put the changes from 2.0 to 3.0 at
the bottom of the page.
On Fri, 30 May 2025 at 11:00, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
If we decide to keep it I think it would be best to have all protocol
changes on a single page. I'd just put the changes from 2.0 to 3.0 at
the bottom of the page.
Attached are my proposed changes which split this page into different
sections, one for each protocol version, with the most recent protocol
changes at the top.
Attachments:
v8-0001-docs-Update-Protocol-Changes-checklist-page-for-p.patchtext/x-patch; charset=US-ASCII; name=v8-0001-docs-Update-Protocol-Changes-checklist-page-for-p.patchDownload
From 5be9d4348f37a0c99faa28d1b29560e4bd5042b4 Mon Sep 17 00:00:00 2001
From: Jelte Fennema-Nio <github-tech@jeltef.nl>
Date: Thu, 26 Jun 2025 23:25:16 +0200
Subject: [PATCH v8] docs: Update Protocol Changes checklist page for protocol
3.2
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.
---
doc/src/sgml/protocol.sgml | 222 +++++++++++++++++++++++--------------
1 file changed, 138 insertions(+), 84 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 82fe3f93761..498c4a18017 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -7770,106 +7770,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>
base-commit: 7fb3c38e7d7d12a742e1e7600879570251e1886a
--
2.43.0
On Thu, 26 Jun 2025 at 18:04, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:
On Fri, 30 May 2025 at 11:00, Jelte Fennema-Nio <postgres@jeltef.nl>
wrote:If we decide to keep it I think it would be best to have all protocol
changes on a single page. I'd just put the changes from 2.0 to 3.0 at
the bottom of the page.Attached are my proposed changes which split this page into different
sections, one for each protocol version, with the most recent protocol
changes at the top.
Thanks Jelte,
Looks good to me
Dave Cramer
On 27/06/2025 14:20, Dave Cramer wrote:
On Thu, 26 Jun 2025 at 18:04, Jelte Fennema-Nio <postgres@jeltef.nl
<mailto:postgres@jeltef.nl>> wrote:On Fri, 30 May 2025 at 11:00, Jelte Fennema-Nio <postgres@jeltef.nl
<mailto:postgres@jeltef.nl>> wrote:If we decide to keep it I think it would be best to have all protocol
changes on a single page. I'd just put the changes from 2.0 to 3.0 at
the bottom of the page.Attached are my proposed changes which split this page into different
sections, one for each protocol version, with the most recent protocol
changes at the top.Thanks Jelte,
Looks good to me
This is largely redundant with the table in section 54.1.4. Protocol
Versions
(https://www.postgresql.org/docs/devel/protocol-overview.html#PROTOCOL-VERSIONS).
I like the details you added on the changes introduced without protocol
bump in v3.0, though.
I'm not sure what exactly to do here. The current docs could certainly
be improved, but this patch isn't quite there yet. Some thoughts/opinions:
* I would like to have more separation between the obsolete v2 protocol
and v3 onwards. The v2 section should be more tucked away.
* I think a table, like in the section 54.1.4 Protocol Versions section,
is better than just text paragraphs. Could have text paragraphs with
more details, but a table gives a good overview.
* The first paragraph in the "Summary of Protocol Changes" section says
"This section provides a quick checklist of changes", but it's more like
an exhaustive list now.
- Heikki
On Tue, 12 Aug 2025 at 10:01, Heikki Linnakangas <hlinnaka@iki.fi> wrote:
This is largely redundant with the table in section 54.1.4. Protocol
Versions
(https://www.postgresql.org/docs/devel/protocol-overview.html#PROTOCOL-VERSIONS).
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?