Subject: pgsql: libpq: Grease the protocol by default

From: Jacob Champion <[email-masked]>
Date: Mon, 23 Feb 2026 18:58:07 +0000

libpq: Grease the protocol by default

Send PG_PROTOCOL_GREASE and _pq_.test_protocol_negotiation, which were
introduced in commit d8d7c5dc8, by default, and fail the connection if
the server attempts to claim support for them. The hope is to provide
feedback to noncompliant implementations and gain confidence in our
ability to advance the protocol. (See the other commit for details.)

To help end users navigate the situation, a link to our documentation
that explains the behavior is displayed. We append this to the error
message when the NegotiateProtocolVersion response is incorrect, or when
the peer sends an error during startup that appears to be grease-
related.

It's still possible for users to connect to servers that don't support
protocol negotiation, by adding max_protocol_version=3.0 to their
connection strings. Only the default connection behavior is impacted.

This commit is tracked as a PG19 open item and will be reverted before
RC1. (The implementation here doesn't handle negotiation with later
server versions, so it can't be released into the wild as a
five-year-supported feature. But an improved implementation might be
able to do so, in the future...)

Author: Jelte Fennema-Nio <[email-masked]>
Co-authored-by: Jacob Champion <[email-masked]>
Discussion: https://postgr.es/m/DDPR5BPWH1RJ.1LWAK6QAURVAY%40jeltef.nl

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/4966bd3ed95e0d02bf220c4bad2b292963827dd4

Modified Files
--------------
doc/src/sgml/libpq.sgml                          | 17 ++++++++
doc/src/sgml/protocol.sgml                       | 11 +++++
src/interfaces/libpq/fe-connect.c                | 51 +++++++++++++++++++-----
src/interfaces/libpq/fe-misc.c                   | 18 +++++++++
src/interfaces/libpq/fe-protocol3.c              | 51 ++++++++++++++++++++++--
src/interfaces/libpq/libpq-int.h                 |  1 +
src/test/modules/libpq_pipeline/libpq_pipeline.c |  6 +--
7 files changed, 140 insertions(+), 15 deletions(-)

---

From: Jacob Champion <[email-masked]>
Date: Mon, 23 Feb 2026 13:17:05 -0800

crake is angry:

> pg_dumpall: error: connection to server on socket "/home/andrew/bf/root/tmp/buildfarm-onigY7/.s.PGSQL.5670" failed: FATAL: unsupported frontend protocol 3.9999: server supports 1.0 to 3.0
> This indicates a bug in either the server being contacted
> or a proxy handling the connection. Please consider
> ...

So while this is kind of a nice result, in that it's correctly
diagnosing the problem, I need to add max_protocol_version=3.0 to the
connection strings for these upgrades during beta.

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Mon, 23 Feb 2026 17:18:09 -0500

[ moving discussion to -hackers ]

> connection strings for these upgrades during beta.

Either that or we decide that it's time to throw 9.2 support
overboard (looks like 9.3 and up are fine).

If it's not hard to add the connection option to this test, let's do
that --- but if it is a problem, I wouldn't shed too many tears over
moving the oldest-old-version goalpost.  I think we might not be able
to fix the test without changing buildfarm client script and/or
configuration.

			regards, tom lane

---

From: Jelte Fennema-Nio <[email-masked]>
Date: Mon, 23 Feb 2026 23:24:34 +0100

> connection strings for these upgrades during beta.

Two thoughts:
1. I think we might want the "This indicates a bug in either the
server being contacted..." note to be added to the error even if you
use 3.2/3.3/3.X. It seems pretty helpful in general. It would need a
bit fancier detection though, with strings to search for based on the
actual requested version.
2. Why only force max_protocol_version=3.0 for beta? It sounds like
this would also be an issue once we eventually bump the default
version.

---

From: Jacob Champion <[email-masked]>
Date: Mon, 23 Feb 2026 14:51:46 -0800

> overboard (looks like 9.3 and up are fine).

Well, while I was hacking on a patch I realized that 9.3 (all the way
up to 10) is only okay if you're running a sufficiently patched
version. PG11 is the first to support negotiation for the whole
release line.

I think Jelte said it well back on the -committers thread:

> Why only force max_protocol_version=3.0 for beta? It sounds like

So a fix belongs in pg_upgrade, IMO, instead of the test. I have a
draft passing locally that I should be able to share soon.

Thanks,
--Jacob

---

From: Tom Lane <[email-masked]>
Date: Mon, 23 Feb 2026 18:34:42 -0500

> version. PG11 is the first to support negotiation for the whole

Hmm ... and of course the whole point of this exercise is to be sure
we can pg_upgrade from those out-of-support versions.

> draft passing locally that I should be able to share soon.

Fair enough.

			regards, tom lane

---

From: Jacob Champion <[email-masked]>
Date: Mon, 23 Feb 2026 15:41:46 -0800

> > draft passing locally that I should be able to share soon.

Something like the attached (tested only against 9.2 so far)? I would
plan to backpatch after feature freeze is lifted.

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Mon, 23 Feb 2026 19:45:05 -0500

> plan to backpatch after feature freeze is lifted.

This does not fix it for me on a local buildfarm instance.  I still get
the same failure during 9.2-to-HEAD cross-version upgrade:

==~_~===-=-===~_~== /home/buildfarm/bf-data/fs-upgrade.tester/HEAD/REL9_2_STABLE-dump1.log ==~_~===-=-===~_~==
pg_dumpall: error: connection to server on socket "/home/buildfarm/bf-data/tmp/buildfarm-0fIcMg/.s.PGSQL.5700" failed: FATAL:  unsupported frontend protocol 3.9999: server supports 1.0 to 3.0
        This indicates a bug in either the server being contacted
        or a proxy handling the connection. Please consider
        reporting this to the maintainers of that software.
        For more information, including instructions on how to
        work around this issue for now, visit
                https://www.postgresql.org/docs/devel/libpq-connect.html#LIBPQ-CONNECT-MAX-PROTOCOL-VERSION

It's not obvious to me where the problem lies.  I can replicate
the failure by trying to use HEAD's psql to connect to a 9.2
server, but adding -d "max_protocol_version=3.0" makes psql happy,
so why not pg_dumpall?

Also: I was initially baffled why you thought this needs
back-patching, but I guess you have one eye on packagers like
Debian who think they can make older versions use newer libpq.so.
It'd be good to spell out that reasoning in the commit message.

			regards, tom lane

---

From: Jacob Champion <[email-masked]>
Date: Mon, 23 Feb 2026 17:05:45 -0800

> > plan to backpatch after feature freeze is lifted.

(er, should have been "release freeze", though we're clearly in no hurry)

> Debian who think they can make older versions use newer libpq.so.

Right.

> It'd be good to spell out that reasoning in the commit message.

Okay, will do.

> server, but adding -d "max_protocol_version=3.0" makes psql happy,

Hmmm, looks like the -dump1.log output is actually from *before*
pg_upgrade actually runs:

    https://github.com/PGBuildFarm/client-code/blob/28d7e945cc2a27fecdf4cc685782821ca504db5d/PGBuild/Modules/TestUpgradeXversion.pm#L514

So that will still need to be modified in the buildfarm client,
independently of my patch. (I reproduced the error with a bare
pg_upgrade invocation and didn't think to look closer; sorry for the
confusion.)

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Mon, 23 Feb 2026 20:17:23 -0500

I wrote:
> It's not obvious to me where the problem lies.

Ah: the step that is failing is where TestUpgradeXVersion.pm
is trying to make a comparison dump from the old server:

	# use the NEW pg_dumpall so we're comparing apples with apples.
	setinstenv($self, "$installdir", $save_env);
	system( qq{"$installdir/bin/pg_dumpall" $dump_opts -p $sport -f }
		  . qq{"$upgrade_loc/origin-$oversion.sql" }
		  . qq{> "$upgrade_loc/$oversion-dump1.log" 2>&1});
	return if $?;

So I was right to suspect that we can't fix this without modifying
the buildfarm client.

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Mon, 23 Feb 2026 21:08:56 -0500

> Right.

Actually, that is going to be harder than you thought, because libpq
before v18 will spit up on connection option "max_protocol_version".
This patch will not work as-is for back-patching unless we care to
also back-patch the addition of that option, which I'd be inclined
to resist.

Fortunately, we long ago had the foresight to invent PQlibVersion,
so you could make addition of the extra option conditional on
PQlibVersion(conn) >= 180000 in branches before 18.

> pg_upgrade actually runs:

Yeah, I came to the same conclusion.  I got a clean BF run using
your patch together with the attached patch for the BF client.
(In this patch, I did not worry about scenarios involving old
minor releases.  If Andrew is excited about that case he can
extend the version-comparison logic.)

			regards, tom lane

--- PGBuild/Modules/TestUpgradeXversion.pm~	2025-11-25 07:47:25.000000000 -0500
+++ PGBuild/Modules/TestUpgradeXversion.pm	2026-02-23 20:57:31.640149574 -0500
@@ -483,9 +483,17 @@ sub test_upgrade    ## no critic (Subrou
 		$dump_opts .= ' --extra-float-digits=0';
 	}
 
+	# with very old servers we must restrict the protocol version.
+	my $maxpversion = "";
+	if (   ($this_branch eq 'HEAD' || $this_branch gt 'REL_18_STABLE')
+		&& ($oversion ne 'HEAD' && $oversion le 'REL_9_2_STABLE'))
+	{
+		$maxpversion = '-d max_protocol_version=3.0';
+	}
+
 	# use the NEW pg_dumpall so we're comparing apples with apples.
 	setinstenv($self, "$installdir", $save_env);
-	system( qq{"$installdir/bin/pg_dumpall" $dump_opts -p $sport -f }
+	system( qq{"$installdir/bin/pg_dumpall" $dump_opts $maxpversion -p $sport -f }
 		  . qq{"$upgrade_loc/origin-$oversion.sql" }
 		  . qq{> "$upgrade_loc/$oversion-dump1.log" 2>&1});
 	return if $?;

---

From: Andrew Dunstan <[email-masked]>
Date: Tue, 24 Feb 2026 10:55:20 -0500

On 2026-02-23 Mo 9:08 PM, Tom Lane wrote:
> Jacob Champion<[email-masked]> writes:
>> On Mon, Feb 23, 2026 at 4:45 PM Tom Lane<[email-masked]> wrote:

I am not worried about old minor releases. I am currently testing a 
patch with similar intent to yours.

cheers

andrew

--
Andrew Dunstan
EDB:https://www.enterprisedb.com

---

From: Nathan Bossart <[email-masked]>
Date: Tue, 24 Feb 2026 10:17:40 -0600

> we can pg_upgrade from those out-of-support versions.

I discussed this a bit on the hacking Discord last year, but IMHO we're
reaching a good point to bump up pg_upgrade's oldest supported major
version.  I'll probably push to bump it to v10 for the v20 release so that
we can remove many of the version-specific hacks we've built up over the
years.  Not to mention that the cross-version tests (the "export
oldinstall" ones described in pg_upgrade's TESTING file, not the buildfarm
ones) don't seem to work past v10 or so because they use various options
that didn't exist or have since been renamed.

Granted, this probably doesn't help the present issue...

-- 
nathan

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 09:18:19 -0800

> before v18 will spit up on connection option "max_protocol_version".

Ha, right. Luckily the failure is very loud when testing :)

> PQlibVersion(conn) >= 180000 in branches before 18.

Attached is a sample backport for REL_14_STABLE, using that strategy.
Tested with pg_upgrade 9.2-to-14, when linked against both 14.22 and
HEAD versions of libpq. I still need to run a sanity check with the
other 9.x lines to make sure I've selected the right cutoffs.

> your patch together with the attached patch for the BF client.

Nice, thanks!

--Jacob

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 09:27:52 -0800

> Granted, this probably doesn't help the present issue...

Yeah, we'd need to go all the way to PG11 to avoid it entirely. But
that's okay -- finding and fixing this now means that we don't have to
relitigate it when bumping the default version later (or when
releasing production-grade grease). If PG10 ages out before we finally
decide to do either one, fine.

--Jacob

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 10:13:02 -0800

On Tue, Feb 24, 2026 at 9:18 AM Jacob Champion
<[email-masked]> wrote:
> I still need to run a sanity check with the

The cutoffs don't behave the way I thought they would.

Yesterday, I was about to complain that cluster.major_version was
poorly named -- why call it that if you have to pass it through
GET_MAJOR_VERSION() to get at what you want? -- but it does in fact
contain _only_ the major version information, because that's all that
PG_VERSION tells us. And unfortunately we don't save the result of the
version check for the old postgres binary anywhere.

So pg_upgrade will use max_protocol_version=3.0 with all servers v10
and below, in practice. There's nothing wrong with that behavior, but
I think I should switch to a simple `< 1100` check in the code to
avoid misleading people, unless anyone has a better way that won't
significantly increase the cost of the backport. (I could potentially
follow up with an improvement on HEAD, if the cost-benefit makes
sense, but I'm not sure it does.)

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Tue, 24 Feb 2026 13:50:33 -0500

Jacob Champion <[email-masked]> writes:
> significantly increase the cost of the backport.

Simple is good here.  I don't think we'd buy much by distinguishing
minor versions of already-EOL servers.  Also, I suspect that
pg_upgrade can't get the minor version except by starting the server
and asking it --- we don't record anything but major version on-disk.

			regards, tom lane

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 10:58:30 -0800

> and asking it --- we don't record anything but major version on-disk.

We do store (the major version part of) `pg_ctl --version` at some
point, which we could improve upon, but I agree that adding additional
complexity here doesn't actually give us any benefit.

--Jacob

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 12:29:02 -0800

> complexity here doesn't actually give us any benefit.

Okay, here are the patches I propose. The ones for 18-HEAD check for
PG10 and below, and 14-17 additionally check that libpq >= 18, before
adding max_protocol_version=3.0.

I smoke-tested upgrades from 9.2, 10.1, and 11.0 for all six branches,
and then re-ran that test matrix with pg_upgrade linked against a
greased libpq.

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Tue, 24 Feb 2026 15:40:38 -0500

> adding max_protocol_version=3.0.

These look sane to me.  I might suggest a small wording change in
the <= 17 patches:

-	 * Back-branch-specific complication: for libpq versions prior to PG18,
+	 * Back-branch-specific complication: in libpq versions prior to PG18,

but it probably isn't worth the trouble to edit four separate patches.

			regards, tom lane

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 14:33:34 -0800

> but it probably isn't worth the trouble to edit four separate patches.

By the power of sed, it is done.

And I see that the new release tags are here, so pushed. Thanks for
all the review and testing!

--Jacob

---

From: Andrew Dunstan <[email-masked]>
Date: Tue, 24 Feb 2026 17:49:32 -0500

> patch with similar intent to yours.

Here's what worked for me, even before Jacob's patch of 15 minutes or so 
ago.

cheers

andrew

--
Andrew Dunstan
EDB: https://www.enterprisedb.com
diff --git a/PGBuild/Modules/TestUpgradeXversion.pm b/PGBuild/Modules/TestUpgradeXversion.pm
index a5e6be5..8e8d262 100644
--- a/PGBuild/Modules/TestUpgradeXversion.pm
+++ b/PGBuild/Modules/TestUpgradeXversion.pm
@@ -513,6 +513,9 @@ sub test_upgrade    ## no critic (Subroutines::ProhibitManyArgs)
 
 	# use the NEW pg_dumpall so we're comparing apples with apples.
 	setinstenv($self, "$installdir", $save_env);
+	local $ENV{PGMAXPROTOCOLVERSION} =
+	  ($oversion le 'REL9_2_STABLE') ? "3.0" : "latest";
+
 	system( qq{"$installdir/bin/pg_dumpall" $dump_opts -p $sport -f }
 		  . qq{"$upgrade_loc/origin-$oversion.sql" }
 		  . qq{> "$upgrade_loc/$oversion-dump1.log" 2>&1});
@@ -575,6 +578,8 @@ sub test_upgrade    ## no critic (Subroutines::ProhibitManyArgs)
 		  . qq{--new-bindir="$installdir/bin" }
 		  . qq{>> "$upgrade_loc/$oversion-upgrade.log" 2>&1});
 
+	delete $ENV{PGMAXPROTOCOLVERSION};
+
 	foreach my $upgradelog (
 		glob(
 			"$installdir/pg_upgrade*

---

From: Jacob Champion <[email-masked]>
Date: Tue, 24 Feb 2026 14:59:04 -0800

> Here's what worked for me, even before Jacob's patch of 15 minutes or so

Oh, the envvar is clever. You'll probably want to do that only for the
pg_dumpall invocation now that pg_upgrade is patched, though, so we
don't cover up regressions.

--Jacob

---

From: Tom Lane <[email-masked]>
Date: Tue, 24 Feb 2026 18:30:35 -0500

> don't cover up regressions.

I agree with Jacob on both points.

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Tue, 24 Feb 2026 20:30:29 -0500

> don't cover up regressions.

I can confirm clean x-version tests on all branches with git tip
and this:

--- TestUpgradeXversion.pm.orig 2025-11-25 07:47:25.000000000 -0500
+++ TestUpgradeXversion.pm      2026-02-24 18:50:29.487530840 -0500
@@ -485,10 +485,14 @@ sub test_upgrade    ## no critic (Subrou
 
        setinstenv($self, "$other_branch/inst", $save_env);
 
        system( qq{"$other_branch/inst/bin/pg_ctl" -D }

which is Andrew's patch but with the envvar dropped as soon
as possible.

			regards, tom lane

---

From: Andrew Dunstan <[email-masked]>
Date: Tue, 24 Feb 2026 21:06:57 -0500

> which is Andrew's patch but with the envvar dropped as soon

Yep. working for me too.

cheers

andrew

---

From: Álvaro Herrera <[email-masked]>
Date: Wed, 25 Feb 2026 11:27:48 +0100

> By the power of sed, it is done.

What I normally do for this kind of thing is commit the typo fix in a
separate commit, then cherry-pick that to other branches, then use
rebase -i to squash it as a fix-up of the previous commit on all
branches.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
Y una voz del caos me habló y me dijo
"Sonríe y sé feliz, podría ser peor".
Y sonreí. Y fui feliz.
Y fue peor.