Thread
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
-
Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-10T09:52:14Z
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
-
Re: Correct documentation for protocol version
Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-04-10T13:54:12Z
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
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-10T14:40:39Z
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-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. > > + 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
-
Re: Correct documentation for protocol version
Jacob Champion <jacob.champion@enterprisedb.com> — 2025-04-10T15:14:55Z
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]. :) --Jacob [1] https://www.postgresql.org/message-id/7a43f140-60e7-87ce-cf68-ea6d40e4b904%40timescale.com
-
Re: Correct documentation for protocol version
Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-04-10T15:17:51Z
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
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-10T15:49:28Z
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-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. Dave
-
Re: Correct documentation for protocol version
Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-04-10T16:17:54Z
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 -
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-10T20:17:06Z
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 < > 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 -
Re: Correct documentation for protocol version
Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-04-11T09:05:14Z
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 -
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-11T09:27:38Z
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 > >
-
Re: Correct documentation for protocol version
Fujii Masao <masao.fujii@oss.nttdata.com> — 2025-04-11T13:39:15Z
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 -
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-11T14:56:45Z
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
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-04-11T14:59:39Z
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.
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-04-11T15:02:27Z
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.
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-04-22T14:34:55Z
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.
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-05-28T22:29:37Z
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 connectin > > I found another place where the docs should be updated. The Changes since Protocol 2.0 See attached patch > >
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-05-29T10:17:57Z
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
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-05-29T11:12:27Z
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
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-05-30T09:00:33Z
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.
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-06-26T22:04:24Z
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.
-
Re: Correct documentation for protocol version
Dave Cramer <davecramer@gmail.com> — 2025-06-27T11:20:38Z
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
-
Re: Correct documentation for protocol version
Heikki Linnakangas <hlinnaka@iki.fi> — 2025-08-12T08:01:45Z
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
-
Re: Correct documentation for protocol version
Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-08-12T09:52:06Z
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?