From ec791d56482888a5a52171c73c42aa32ac300d0d Mon Sep 17 00:00:00 2001 From: Jelte Fennema-Nio Date: Fri, 23 Jan 2026 22:32:20 +0100 Subject: [PATCH v5 5/5] Update libpq docs for better grease Kept separate from the previous two patches for now while we discuss the actual details of the implementation. --- doc/src/sgml/libpq.sgml | 26 ++++++++++----- doc/src/sgml/protocol.sgml | 68 ++++++++++++++++++++++++-------------- 2 files changed, 62 insertions(+), 32 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index fb6ce177f0d..d785f18914f 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -2213,10 +2213,17 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Specifies the protocol version to request from the server. - During the PostgreSQL 19 beta period, the default is to use - 3.9999, a GREASE (Generate Random Extensions And - Sustain Extensibility) value that tests proper protocol negotiation - implementation. If the server does not support the protocol version + During the PostgreSQL 19 beta period, the default is + grease, which requests a random protocol version in + the range 3.9990-3.9999 and includes 0-5 random GREASE startup + parameters. This tests that servers and middleware properly implement + protocol version negotiation. The default will be changed to + latest before PostgreSQL 19 is released, but the + grease option will remain available for testing. + + + + If the server does not support the protocol version requested by the client, the connection is automatically downgraded to a lower minor protocol version that the server supports. After the connection attempt has completed you can use @@ -2232,10 +2239,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname The current supported values are - 3.0, 3.2, - and latest. The latest value is - equivalent to the latest protocol version supported by the libpq - version being used, which is currently 3.2. + 3.0, + 3.2, + latest, and + grease. + The latest value is equivalent to the latest + protocol version supported by the libpq version being used, which is + currently 3.2. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 78d272ccc50..922b7ca3b1d 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -193,12 +193,13 @@ The current, latest version of the protocol is version 3.2. During the - PostgreSQL 19 beta period, libpq defaults to requesting protocol version - 3.9999 to test that servers and middleware properly implement protocol - version negotiation. Servers that support negotiation will automatically - downgrade to version 3.2 or 3.0. For servers that don't support - negotiation, users can connect by explicitly setting - max_protocol_version=3.0 in their connection string. + PostgreSQL 19 beta period, libpq defaults to requesting a random protocol + version in the range 3.9990-3.9999 (the GREASE range) to test that servers + and middleware properly implement protocol version negotiation. Servers + that support negotiation will automatically downgrade to version 3.2 or + 3.0. For servers that don't support negotiation, users can connect by + explicitly setting max_protocol_version=3.0 in their + connection string. @@ -242,17 +243,17 @@ - 3.9999 + 3.9990-3.9999 - GREASE (Generate Random Extensions And Sustain Extensibility) - version. This version number is intentionally reserved and will never - be implemented. During the PostgreSQL 19 beta period, libpq requests - this version by default to test that servers and middleware properly - implement protocol version negotiation via + version range. These version numbers are intentionally reserved and + will never be implemented. Clients can request a random version from + this range to test that servers and middleware properly implement + protocol version negotiation via NegotiateProtocolVersion. Servers should respond by downgrading to a supported version. This mechanism helps ensure - the ecosystem is ready for future protocol versions. libpq will revert - to defaulting to version 3.0 before the PostgreSQL 19 final release. + the ecosystem is ready for future protocol versions. libpq supports + this via max_protocol_version=grease. @@ -319,21 +320,40 @@ - test_protocol_negotiation + test_protocol_negotiation_XXXX - - - - A reserved protocol extension requested by libpq to test that servers - properly implement protocol version negotiation. When the client - requests a GREASE protocol version, this parameter is automatically - included in the startup packet too. Servers should report it as - unsupported in their NegotiateProtocolVersion - response. In GREASE mode the connection will fail if the server - doesn't report this parameter as unsupported, ensuring comprehensive - implementation of protocol negotiation. This parameter is reserved and - will never actually be implemented by a server. + + Reserved GREASE (Generate Random Extensions And Sustain Extensibility) + protocol extensions. The XXXX can be replaced for any random hex + number. These protocol extensions will never be implemented by a + server, and they should thus report them as unsupported in their + NegotiateProtocolVersion response. Clients are free + to request them to ensure a comprehensive implementation of the + protocol negotiation. As an example libpq sends 0-5 of these parameters + when max_protocol_version=grease. + + negotiation_test_XXXX + - + - + + + protocol_grease_XXXX + - + - + + + grease_the_server_XXXX + - + - + + + always_unknown_extension_XXXX + - + - + -- 2.52.0