Re: Correct documentation for protocol version - Mailing list pgsql-hackers

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
returnthe 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.
Attachedis 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
neverhandled 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