Re: Correct documentation for protocol version

Fujii Masao <masao.fujii@oss.nttdata.com>

From: Fujii Masao <masao.fujii@oss.nttdata.com>

To: Dave Cramer <davecramer@gmail.com>

Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>

Date: 2025-04-11T09:05:14Z

Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

Do not hardcode PG_PROTOCOL_LATEST in NegotiateProtocolVersion
- 516b87502dc1 18.0 cited


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