libpq: Bump protocol version to version 3.2 at least until the first/second beta

On Thu Oct 23, 2025 at 3:56 PM CEST, Jelte Fennema-Nio wrote:

So I'm
proposing that we bump the default protocol version that libpq requests
on the master branch, so that users running the latest master against a
proxy that does not support the version negototian will be notified.

Rebased to resolve conflict

On Thu, Oct 23, 2025 at 6:56 AM Jelte Fennema-Nio <me@jeltef.nl> wrote:

Depending on how this works in practice we'll likely still want to
revert this change before we actually release PG19. If we do that before
19beta1 we still have roughly half a year where people will test the
ecosystem.

I think the whole plan probably belongs in the user documentation.
Even if no one were to read it, I still wouldn't want the declaration
that "we default to the latest" to be mixed into the growing search
engine slop pile.

Is there an even stronger way for us to grease this? For example,
could we agree that no one will ever implement 0003.7FFF and push that
during the beta, failing if anyone gives us an unsupported version?

--Jacob

On Fri, 31 Oct 2025 at 17:24, Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

I still wouldn't want the declaration
that "we default to the latest" to be mixed into the growing search
engine slop pile.

Fair enough (although the intent is to get to that state at some point).

Is there an even stronger way for us to grease this? For example,
could we agree that no one will ever implement 0003.7FFF and push that
during the beta, failing if anyone gives us an unsupported version?

I quite like that idea! Although maybe not 7FFF, but 270F so that
PQfullProtocolVersion returns 39999. And I think it'd be good to also
add a protocol option, like _pq_.test_protocol_breakage and fail the
connection attempt client side if that does not get returned back as
unsupported. I'll try to update this patch to do that in the coming days.

On Fri, Oct 31, 2025 at 2:56 PM Jelte Fennema-Nio <me@jeltef.nl> wrote:

I quite like that idea! Although maybe not 7FFF, but 270F so that
PQfullProtocolVersion returns 39999.

+1

And I think it'd be good to also
add a protocol option, like _pq_.test_protocol_breakage and fail the
connection attempt client side if that does not get returned back as
unsupported.

Yeah, I feel better signing on to a plan like this if we think the
breakage is likely to lead to a comprehensive fix for
NegotiateProtocolVersion (as opposed to "we greased this thing in 2025
and now this thing in 2026 and now...").

Thanks,
--Jacob

On Fri Oct 31, 2025 at 11:52 PM CET, Jacob Champion wrote:

On Fri, Oct 31, 2025 at 2:56 PM Jelte Fennema-Nio <me@jeltef.nl> wrote:
Yeah, I feel better signing on to a plan like this if we think the
breakage is likely to lead to a comprehensive fix for
NegotiateProtocolVersion (as opposed to "we greased this thing in 2025
and now this thing in 2026 and now...").

Attached is a new version of the patch that reserves version 3.9999 and
_pq_.test_protocol_negotiation and starts requesting those by default
(which we should revert before at least PG19rc1 and possibly earlier).

Hi,

On 2025-11-03 15:46:10 +0100, Jelte Fennema-Nio wrote:

From 31851ddff8cb40f732aac0bfac364da61ed9fa30 Mon Sep 17 00:00:00 2001
From: Jelte Fennema-Nio <postgres@jeltef.nl>
Date: Thu, 23 Oct 2025 15:08:52 +0200
Subject: [PATCH v3 2/2] libpq: Request protocol version 3.9999 to GREASE the
ecosystem

The main reason that libpq does not request protocol version 3.2 by
default is because other proxy/server implementations don't implement
the negotiation. This is a bit of a chicken and egg problem: We don't
bump the default version that libpq asks, but proxies will only
implement version negotiation when their users run into issues.

This patch defines 3.999 as an explicitly unsupported protocol version
number and _pq_.test_protocol_negotiation as an explicitly unsupported
protocol extension. It also starts requesting that version and protocol
extension by default. This change to the default will be reverted before
we release PG19 release candidates (when exactly to revert before that
time is TBD). The intent is to stress test the ecosystem for
servers/middleware that don't support protocol version negotiation, so
that those servers/middleware can implement the negotiation. This is
similar to the GREASE[1] mechanism that TLS has.

It's still possible for users to connect to servers that don't support
protocol negotiation by using max_protocol_version=3.0 in their
connection string. Only the default connection behaviour is impacted.

[1]: https://www.rfc-editor.org/rfc/rfc8701.html

Won't this mean that it'll be harder to performance comparisons between the
in-development version and other versions? Because there will be negotiation
before we branch of 19, but not after and not in release branches?

Greetings,

Andres Freund

On Mon, 3 Nov 2025 at 15:59, Andres Freund <andres@anarazel.de> wrote:

Won't this mean that it'll be harder to performance comparisons between the
in-development version and other versions? Because there will be negotiation
before we branch of 19, but not after and not in release branches?

The negotiation does not require a separate roundtrip, only a tiny
additional message sent by the server. So I'm not worried about that
resulting in a measurable perf change. And even if there is one in
some super extreme benchmark, then you can still set
max_protocol_version=3.0 to revert to the regular behaviour.

On Mon, Nov 3, 2025 at 7:42 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

The negotiation does not require a separate roundtrip, only a tiny
additional message sent by the server. So I'm not worried about that
resulting in a measurable perf change. And even if there is one in
some super extreme benchmark, then you can still set
max_protocol_version=3.0 to revert to the regular behaviour.

Andres, should I take from the silence that you're satisfied with that?

On Mon, Nov 3, 2025 at 6:46 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

Attached is a new version of the patch that reserves version 3.9999 and
_pq_.test_protocol_negotiation and starts requesting those by default
(which we should revert before at least PG19rc1 and possibly earlier).

Partial review follows, in a v4 squash! set, as requested on the Discord :)

v4-0001 and 0002 should be identical to v3, modulo any rebased diff context.

v4-0003: I was initially confused about the need to change the
max_protocol_version_index logic in v3-0001 (it's because empty
parameter values are ignored by PQconnectdbParams). Then I decided
that if we have to maintain the logic to overwrite
max_protocol_version in-place, we might as well always use it. v4-0003
does that and adds some explanation.

v4-0004 does a cosmetic move of the PG_PROTOCOL_GREASE macro now that
we have a section for it.

v4-0005 is a temporary distraction to move protocol version 3.1 into
the same place. If people don't like it I'm happy to drop it for now
(it may deserve at least some bikeshedding on the macro name, since
it's part of a public header).

= Additional Thoughts =

I want to more clearly decouple ourselves from TLS's GREASE in the
documentation and comments. We aren't "Generating Random Extensions"
(we _could_, but that takes a lot more thought), nor are we telling
OpenSSL to enable GREASE for our TLS connections. It's fine if we want
to gesture in that direction as broader context, but I don't want to
cause user confusion. I'll work on some proposed changes for that.

I'd like reserve a (protected?) wiki page, or something of the sort,
that we can point people to directly if they hit any grease failures.
"Server screwed up" is probably not enough context for a typical user
to know what to do next.

I will also work on splitting 0002 into revertable and not-revertable
halves. The grease constant probably needs to remain documented and
reserved even if it doesn't do anything for 19.0.

Finally: is there any appetite for retaining the ability to grease
connections as production functionality, e.g. via
`max_protocol_version=grease`? Personally I think it'd be nice, but
it's not a trivial amount of extra work. We'd have to handle the case
where a future server responds with a legitimate minor version that's
newer than what our version of libpq supports. And I think we'd want a
production-grade version of this to add some randomization tricks, to
discourage people from keying on grease constants.

Thanks,
--Jacob

On 2026-01-14 12:23:24 -0800, Jacob Champion wrote:

On Mon, Nov 3, 2025 at 7:42 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

The negotiation does not require a separate roundtrip, only a tiny
additional message sent by the server. So I'm not worried about that
resulting in a measurable perf change. And even if there is one in
some super extreme benchmark, then you can still set
max_protocol_version=3.0 to revert to the regular behaviour.

Andres, should I take from the silence that you're satisfied with that?

My concern about that aspect has been ameliorated, I have however not
looked/thought about anything else in this proposal.

On Wed, Jan 14, 2026 at 1:43 PM Andres Freund <andres@anarazel.de> wrote:

My concern about that aspect has been ameliorated, I have however not
looked/thought about anything else in this proposal.

Excellent, thanks!

--Jacob

On Wed Jan 14, 2026 at 9:23 PM CET, Jacob Champion wrote:

Partial review follows, in a v4 squash! set, as requested on the Discord :)

All changes in those 3 additional patches look totally reasonable to me.

= Additional Thoughts =

I want to more clearly decouple ourselves from TLS's GREASE in the
documentation and comments. We aren't "Generating Random Extensions"
(we _could_, but that takes a lot more thought), nor are we telling
OpenSSL to enable GREASE for our TLS connections. It's fine if we want
to gesture in that direction as broader context, but I don't want to
cause user confusion. I'll work on some proposed changes for that.

Yeah, I didnt't realize that since TLS GREASE it became a broader term.
Definitely seems reasonable to reference the generic grease RFC instead
(which you have shared in the other protocol thread I think). So yeah
feel free to change the docs/comments to your heart's content.

I'd like reserve a (protected?) wiki page, or something of the sort,
that we can point people to directly if they hit any grease failures.
"Server screwed up" is probably not enough context for a typical user
to know what to do next.

Seems sensible to have a place to explain something to authors. Why not
put it directly in the protocol docs though? (I'd be fine with a wiki
too, but a docs page is protected by definition)

I will also work on splitting 0002 into revertable and not-revertable
halves. The grease constant probably needs to remain documented and
reserved even if it doesn't do anything for 19.0.

Finally: is there any appetite for retaining the ability to grease
connections as production functionality, e.g. via
`max_protocol_version=grease`? Personally I think it'd be nice, but
it's not a trivial amount of extra work. We'd have to handle the case
where a future server responds with a legitimate minor version that's
newer than what our version of libpq supports. And I think we'd want a
production-grade version of this to add some randomization tricks, to
discourage people from keying on grease constants.

Both the patch split and max_protocol_version=grease sound reasonable to
me. I'd definitely like to keep all the grease code present on the main
branch, so we can keep using grease by default there.

I think max_protocol_version=grease makes a lot of sense. Because we
really want to make it as easy as possible for people to try out their
implementation of the negotation (see this for example[1]https://github.com/pgdogdev/pgdog/issues/578#issuecomment-3437244304)

If we do that then the patch split would be fairly minimal I expect.
i.e. it should only change the libpq default value, and the accompanying
test that tests the default value.

[1]: https://github.com/pgdogdev/pgdog/issues/578#issuecomment-3437244304

On Wed, Jan 14, 2026 at 2:16 PM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

All changes in those 3 additional patches look totally reasonable to me.

Thanks, I'll plan to squash those in v5, and probably kick 0005 out
into its own thread to give people a chance to object even if they're
ignoring the grease stuff.

I'd like reserve a (protected?) wiki page, or something of the sort,
that we can point people to directly if they hit any grease failures.
"Server screwed up" is probably not enough context for a typical user
to know what to do next.

Seems sensible to have a place to explain something to authors. Why not
put it directly in the protocol docs though? (I'd be fine with a wiki
too, but a docs page is protected by definition)

At the moment I can think of two reasons to put a "landing page" for
this in the wiki:

- Suggested improvements by users who land there can be made
immediately/cheaply/ephemerally, without either increasing the revert
burden mid-beta or making a committer feel that they have to wait to
get it "perfect" (because otherwise they flood the Postgres commit
graph with wiki-sized edits that are just going to be reverted
anyway). I think this grease phase will work best if we can be
maximally responsive to the people who take the time to talk to us.

- Informal, personal wiki voice (plus the ability to see a recent edit
date -- "yes, we're paying attention to you") seems like a better way
to encourage beta users to file bugs than formal project documentation
voice. YMMV on that.

Both the patch split and max_protocol_version=grease sound reasonable to
me. I'd definitely like to keep all the grease code present on the main
branch, so we can keep using grease by default there.

I think max_protocol_version=grease makes a lot of sense. Because we
really want to make it as easy as possible for people to try out their
implementation of the negotation (see this for example[1])

Yeah, I'd like to have that ability too. I don't know that I can
commit to writing or reviewing that amount of code for 19, though.
(And maybe there are lessons we'll learn during beta that can inform a
better production feature?)

--Jacob

On Wed, Jan 14, 2026 at 2:56 PM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

I think max_protocol_version=grease makes a lot of sense. Because we
really want to make it as easy as possible for people to try out their
implementation of the negotation (see this for example[1])

Yeah, I'd like to have that ability too. I don't know that I can
commit to writing or reviewing that amount of code for 19, though.
(And maybe there are lessons we'll learn during beta that can inform a
better production feature?)

Per offline confusion/discussion: I plan to work on a grease feature
for beta _regardless_ of whether a "production-grade"
max_protocol_version=grease option turns out to be viable before
feature freeze; do not feel like you "have" to put work into the
latter just to get the former. Sorry about that.

--Jacob

On Wed, Jan 14, 2026 at 2:56 PM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

Thanks, I'll plan to squash those in v5, and probably kick 0005 out
into its own thread to give people a chance to object even if they're
ignoring the grease stuff.

0001, 0003, and 0005 are committed. v5 is attached with several
changes, described below.

On Wed, Jan 14, 2026 at 12:23 PM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

I want to more clearly decouple ourselves from TLS's GREASE in the
documentation and comments.

Done. Unfortunately the rewrites were too difficult to put into nice
squash! commits, since they ended up being spread across the split
described below, so I've also attached an "overall" diff file to try
to highlight what I changed from v3-0002.

One thing I tried to do here was separate the beta-only behavior into
<note>s, so that documentation writers can still review and patch the
language that's going to be published for release. I don't think that
will confuse the limited audience that is going to be reading this.

I will also work on splitting 0002 into revertable and not-revertable
halves. The grease constant probably needs to remain documented and
reserved even if it doesn't do anything for 19.0.

Done. My proposed split is in v5-0002 (which stays) and -0003 (which
gets reverted).

I also added an 0001 which (IMO) improves our documentation around
this, and adds a registry of sorts for the protocol extension
parameters. I'm not completely thrilled about the code and formatting
of that new registry table, but I think what I have is better than
nothing, so I'm going to stop fighting with docbook about this.

I'd like reserve a (protected?) wiki page, or something of the sort,
that we can point people to directly if they hit any grease failures.

This still needs to be done/discussed, but we have a good amount of time.

Finally: is there any appetite for retaining the ability to grease
connections as production functionality, e.g. via
`max_protocol_version=grease`?

This is on the back burner for now. (As stated upthread, it doesn't
need to block the beta-only behavior.)

WDYT?

Thanks,
--Jacob

On Thu Jan 15, 2026 at 1:31 AM CET, Jacob Champion wrote:

Per offline confusion/discussion: I plan to work on a grease feature
for beta _regardless_ of whether a "production-grade"
max_protocol_version=grease option turns out to be viable before
feature freeze;

I saw that you committed a few patches. Given that you said you wanted
to wordsmith the last one, this seemed like a good time to send in some
of my own improvements in that regard. (I did not change the GREASE
mentions, since you clearly had something in mind for those).

0001 is mine an your squash commit, squashed together and rebased on top of main.

0002 is the improvements to the docs. The one important thing is a
change from 3.2 to 3.0. Other than that it introduces a table for
tracking protocol extensions. That way other patches (like GoAway)
that introduce a protocol extension already have some location in
the docs where it can be listed.

0003-0005 are an attempt at making a bit more of a robust GREASE. 0003
makes it "harder to still implement negotation incorrectly". Then 0004
makes it not a hard failure if you connect with
max_protocol_version=grease to a new server. Then 0005 adds some
preliminary docs. These almost certainly need some more discussion. And
I don't expect them to necessarily get in for PG19, but if you like some
of it feel free to pick and take what you want from them. e.g. the
randomized protocol extensions are kinda nice IMO. But I'm not exactly
sure if the randomized version number is that much more useful though
than a fixed one.

On Fri, Jan 23, 2026 at 3:40 PM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

I saw that you committed a few patches. Given that you said you wanted
to wordsmith the last one, this seemed like a good time to send in some
of my own improvements in that regard.

(Well, that was impressive timing.)

--Jacob

On Sat, 24 Jan 2026 at 00:38, Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

WDYT?

Overall, I think the changes and the split look fine. And I'd be happy
with having it committed as is.

A few thoughts on the docs:
1. I like the version table split. I think it might be better to do
the same for protocol extensions too. Primarily because I think the
tiny empty cell at the start of each row looks weird (see screenshot),
but also just for consistency.
2. In my v5 I created a dedicated section header for protocol
extensions instead of including it in the extension. I think that's
slightly nicer, primarily so you can link to that section from the
StartupMessage docs (including the introductory paragraph), instead of
having to link to the table.
3. In the table in my v5 I use "extension name" as a column instead of
"parameter name" so I did not have to include the "_pq_." prefix. I'm
going a bit back and forth between which I like better.
4. I think mentioning the "_pq_." prefix in the paragraph above the
extension table would be good. Otherwise once we get more extensions
you only learn about it once you get to the reserved extensions
section.

A few thoughts on the implementation:
1. If you like the randomization I did in my v5-0003, but don't want
to commit it yet. Then I think it would be good to change the reserved
protocol extension to rename to _pq_.test_protocol_negotiation_0000.
So that if we commit it later we don't have both
_pq_.test_protocol_negotiation and _pq_.test_protocol_negotiation_XXXX
reserved, but only have the one with a suffix reserved.
2. It might be nice to also error duplicate keys in NegotiateProtocolVersion.

On Sat, Jan 24, 2026 at 2:10 AM Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

A few thoughts on the docs:
1. I like the version table split. I think it might be better to do
the same for protocol extensions too. Primarily because I think the
tiny empty cell at the start of each row looks weird (see screenshot),

I figured that would be a sticking point. Docbook really does not want
to help me out here.

but also just for consistency.

As long as the consistency provides *clarity*, I'm fine with it; I'm
just not sure that it does. I'll post a v6 with some screenshots.

2. In my v5 I created a dedicated section header for protocol
extensions instead of including it in the extension. I think that's
slightly nicer, primarily so you can link to that section from the
StartupMessage docs (including the introductory paragraph), instead of
having to link to the table.

Agreed, will fix.

3. In the table in my v5 I use "extension name" as a column instead of
"parameter name" so I did not have to include the "_pq_." prefix. I'm
going a bit back and forth between which I like better.

I feel more strongly about including `_pq_.` in the full parameter
name, because the namespace isn't immediately clear otherwise. Adding
a note in the paragraph above doesn't immediately broadcast that every
single _pq_ parameter is reserved for future protocol work.

(Also, I wonder if we should eventually move the "currently recognized
application-level parameter" table out of StartupMessage, and the
prefix inclusion is even more important then. I'd feel better about
doing that if the docs were a little easier to navigate; there was a
Discord conversation along those lines semi-recently. Something for
another thread.)

A few thoughts on the implementation:
1. If you like the randomization I did in my v5-0003

From a quick skim, I do like it, thank you! My favorite part is the
ability to send multiple grease parameters. I think the minor version
randomization is probably a weaker aspect of the patch, because the
difference in difficulty between "==" and ">=" in a misbehaving server
is much less than our new maintenance cost for randomizing it.

but don't want
to commit it yet.

I won't focus on that just yet. I'd like opinions from other people,
and at least one other maintainer, on a proposed
`max_protocol_version=grease` for production use.

Then I think it would be good to change the reserved
protocol extension to rename to _pq_.test_protocol_negotiation_0000.
So that if we commit it later we don't have both
_pq_.test_protocol_negotiation and _pq_.test_protocol_negotiation_XXXX
reserved, but only have the one with a suffix reserved.

I think we can safely include the shorter one in a future suffix
reservation, just by moving where the "wildcard" is, so I'm not too
worried about that at the moment. But let me know if you feel strongly
about it.

2. It might be nice to also error duplicate keys in NegotiateProtocolVersion.

I'm skeptical unless
- we change the protocol itself to disallow duplicate parameters, in
which case we don't have to grease it; or
- you know of a specific reason a duplicate key in NPV could cause
interoperability problems?

(For greenfield protocol design, I'm right there with you.)

Thanks,
--Jacob

On Fri, Jan 30, 2026 at 10:06 AM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:

2. In my v5 I created a dedicated section header for protocol
extensions instead of including it in the extension. I think that's
slightly nicer, primarily so you can link to that section from the
StartupMessage docs (including the introductory paragraph), instead of
having to link to the table.

Agreed, will fix.

Done in v6-0001. v6-0002/3 are the same as v5.

As long as the consistency provides *clarity*, I'm fine with it; I'm
just not sure that it does. I'll post a v6 with some screenshots.

screenshot-1.png shows what the combined table looks like under our
website CSS. The indent is still odd, but it looks less jarring when
"themed", IMHO.

v6-0004 is a squash commit that splits the table instead.
screenshot-2.png shows the effect of the split. I really don't like
it, but I won't die on that hill.

--Jacob