Horton

Thread

Commits

  1. Doc: fix outdated protocol version.

  1. PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-06-26T06:56:08Z

    In the PG18 docs, I see:
https://www.postgresql.org/docs/18/protocol-message-formats.html

StartupMessage (F)
:
Int32(196608)

    The protocol version number. The most significant 16 bits are the
    major version number (3 for the protocol described here). The
    least significant 16 bits are the minor version number (0 for the
    protocol described here).

In my understanding PG18 will support protocol version 3.2, but above
statement claims that the protocol minor version is 0. Initially I
thought this is because libpq will use 3.0 unless max_protocol_version
is specified as a connection string. But in the BackendKeyData section
of the doc, it clearly explains v3.2 format. So I suspect this is just
a typo.

Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

  2. Re: PG18 protocol version

    Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-06-26T08:14:57Z

    On Thu, 26 Jun 2025 at 08:56, Tatsuo Ishii <ishii@postgresql.org> wrote:
> So I suspect this is just a typo.

Yeah it seems we didn't update this part of the docs. Attached is a
patch to fix that.

  3. Re: PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-06-26T10:16:29Z

    > Yeah it seems we didn't update this part of the docs. Attached is a
> patch to fix that.

> -         the major version number (3 for the protocol described here).
> -         The least significant 16 bits are the minor version number
> -         (0 for the protocol described here).

Why do you remove the info?
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

  4. Re: PG18 protocol version

    Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-06-26T10:43:44Z

    On Thu, 26 Jun 2025 at 12:16, Tatsuo Ishii <ishii@postgresql.org> wrote:
> Why do you remove the info?

I didn't? I replaced it with a more generic version of the same
information, that covers both protocol version 3.0 and 3.2 (and any
future 3.x)

  5. Re: PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-06-26T11:34:14Z

    > I didn't? I replaced it with a more generic version of the same
> information, that covers both protocol version 3.0 and 3.2 (and any
> future 3.x)

I meant this.
>> -         (0 for the protocol described here).

With your patch the explanation that this document (Message Formats)
is for 3.2, is gone. But maybe it's okay since "54.1.4. Protocol
versions" already stats that the whole F/B protocol docs is for 3.2.

What do you think?
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

  6. Re: PG18 protocol version

    Aleksander Alekseev <aleksander@timescale.com> — 2025-06-26T12:46:15Z

    Hi,

> I meant this.
> >> -         (0 for the protocol described here).
>
> With your patch the explanation that this document (Message Formats)
> is for 3.2, is gone. But maybe it's okay since "54.1.4. Protocol
> versions" already stats that the whole F/B protocol docs is for 3.2.
>
> What do you think?

I reviewed v1 and it looks OK to me.

The text gives an example on our most recent protocol version 3.2. In
the future even if we introduce 3.3 the text is still going to be
valid. This text describes StartupMessage, not all protocol versions
we support.

The problem with the current text is that it implies that the protocol
version can only be 3.0 (=196608) which is wrong.

-- 
Best regards,
Aleksander Alekseev

  7. Re: PG18 protocol version

    Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-06-26T13:32:21Z

    On Thu, 26 Jun 2025 at 13:34, Tatsuo Ishii <ishii@postgresql.org> wrote:
>
> > I didn't? I replaced it with a more generic version of the same
> > information, that covers both protocol version 3.0 and 3.2 (and any
> > future 3.x)
>
> I meant this.
> >> -         (0 for the protocol described here).
>
> With your patch the explanation that this document (Message Formats)
> is for 3.2, is gone. But maybe it's okay since "54.1.4. Protocol
> versions" already stats that the whole F/B protocol docs is for 3.2.
>
> What do you think?

Let me rephrase what you are saying to be sure I understand it
correctly: Since it's stated in the page that the page describes the
3.2 protocol specifically, arguably there's only one valid
StartupMessage within that context, i.e. the one with 196610.

I agree that that's strictly true, but I think I still prefer my newly
proposed wording for a few reasons:
1. My new wording is generic enough that we don't need to update it in
the future.
2. A 3.2 server will currently still receive a 3.0 message, and might
want to support downgrading. Or maybe it will get a 3.3
StartupMessage, to which it should respond with a
NegotiateProtocolVersion message. The new wording makes it clear that
the version in the StartupMessage isn't necessarily a fixed number.
3. As a user of the docs I think the 196608/196610 decimal is more
confusing than helpful. Anything that implements the protocol would
benefit from using the hexadecimal representation instead in its code
(at least until we reach protocol version 3.10).

  8. Re: PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-06-27T13:14:54Z

    > Let me rephrase what you are saying to be sure I understand it
> correctly: Since it's stated in the page that the page describes the
> 3.2 protocol specifically, arguably there's only one valid
> StartupMessage within that context, i.e. the one with 196610.

Your rephrasing is correct.

> I agree that that's strictly true, but I think I still prefer my newly
> proposed wording for a few reasons:
> 1. My new wording is generic enough that we don't need to update it in
> the future.
> 2. A 3.2 server will currently still receive a 3.0 message, and might
> want to support downgrading. Or maybe it will get a 3.3
> StartupMessage, to which it should respond with a
> NegotiateProtocolVersion message. The new wording makes it clear that
> the version in the StartupMessage isn't necessarily a fixed number.

I am not sure when we create 3.3 protocol, we do not want to up date
"As an example protocol version 3.2" to "As an example protocol
version 3.3". If we would want to update it anyway, I would prefer
"Current protocol version 3.2" over "An as example protocol version
3.2" because it's easy to understand. But I think it's a matter of
taste.

> 3. As a user of the docs I think the 196608/196610 decimal is more
> confusing than helpful. Anything that implements the protocol would
> benefit from using the hexadecimal representation instead in its code
> (at least until we reach protocol version 3.10).

Yeah. I always translate deciaml to hexa using bc command when reading
the docs.

If there's no objection, I would like to push the patch.
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

  9. Re: PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-07-03T02:11:45Z

    >> I agree that that's strictly true, but I think I still prefer my newly
>> proposed wording for a few reasons:
>> 1. My new wording is generic enough that we don't need to update it in
>> the future.
>> 2. A 3.2 server will currently still receive a 3.0 message, and might
>> want to support downgrading. Or maybe it will get a 3.3
>> StartupMessage, to which it should respond with a
>> NegotiateProtocolVersion message. The new wording makes it clear that
>> the version in the StartupMessage isn't necessarily a fixed number.
> 
> I am not sure when we create 3.3 protocol, we do not want to up date
> "As an example protocol version 3.2" to "As an example protocol
> version 3.3". If we would want to update it anyway, I would prefer
> "Current protocol version 3.2" over "An as example protocol version
> 3.2" because it's easy to understand. But I think it's a matter of
> taste.
> 
>> 3. As a user of the docs I think the 196608/196610 decimal is more
>> confusing than helpful. Anything that implements the protocol would
>> benefit from using the hexadecimal representation instead in its code
>> (at least until we reach protocol version 3.10).
> 
> Yeah. I always translate deciaml to hexa using bc command when reading
> the docs.
> 
> If there's no objection, I would like to push the patch.

After thinking more, I reached a conclusion it would better to apply
attached simple patch to v18 since v18 is already in the beta phase
and we want to make changes to it minimal.

For master, I would like to push your patch because your patch
includes a fix plus enhancement, therefore better fits to the
development branch (i,e, master).

Best regards,
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp

  10. Re: PG18 protocol version

    Jelte Fennema-Nio <postgres@jeltef.nl> — 2025-07-03T05:50:05Z

    On Thu, 3 Jul 2025 at 04:11, Tatsuo Ishii <ishii@postgresql.org> wrote:
> After thinking more, I reached a conclusion it would better to apply
> attached simple patch to v18 since v18 is already in the beta phase
> and we want to make changes to it minimal.

I thought that clarifying docs was exactly one of the things the beta
period is about. But if not, your patch seems fine too.

CC-ing RMT for clarification

  11. Re: PG18 protocol version

    Tatsuo Ishii <ishii@postgresql.org> — 2025-07-11T01:47:04Z

    > On Thu, 3 Jul 2025 at 04:11, Tatsuo Ishii <ishii@postgresql.org> wrote:
>> After thinking more, I reached a conclusion it would better to apply
>> attached simple patch to v18 since v18 is already in the beta phase
>> and we want to make changes to it minimal.
> 
> I thought that clarifying docs was exactly one of the things the beta
> period is about. But if not, your patch seems fine too.
> 
> CC-ing RMT for clarification

I have pushed my patch to REL_18_STABLE branch and your patch to master.

Thanks.
--
Tatsuo Ishii
SRA OSS K.K.
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp