v5-0005-Update-libpq-docs-for-better-grease.patch

From ec791d56482888a5a52171c73c42aa32ac300d0d Mon Sep 17 00:00:00 2001
From: Jelte Fennema-Nio <postgres@jeltef.nl>
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
       <listitem>
        <para>
         Specifies the protocol version to request from the server.
-        During the PostgreSQL 19 beta period, the default is to use
-        <literal>3.9999</literal>, 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
+        <literal>grease</literal>, 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
+        <literal>latest</literal> before PostgreSQL 19 is released, but the
+        <literal>grease</literal> option will remain available for testing.
+       </para>
+
+       <para>
+        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
 
        <para>
         The current supported values are
-        <literal>3.0</literal>, <literal>3.2</literal>,
-        and <literal>latest</literal>. The <literal>latest</literal> value is
-        equivalent to the latest protocol version supported by the libpq
-        version being used, which is currently <literal>3.2</literal>.
+        <literal>3.0</literal>,
+        <literal>3.2</literal>,
+        <literal>latest</literal>, and
+        <literal>grease</literal>.
+        The <literal>latest</literal> value is equivalent to the latest
+        protocol version supported by the libpq version being used, which is
+        currently <literal>3.2</literal>.
        </para>
       </listitem>
      </varlistentry>
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 @@
 
    <para>
     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
-    <literal>max_protocol_version=3.0</literal> 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 <literal>max_protocol_version=3.0</literal> in their
+    connection string.
    </para>
 
    <para>
@@ -242,17 +243,17 @@
 
      <tbody>
       <row>
-      <entry>3.9999</entry>
+      <entry>3.9990-3.9999</entry>
       <entry>-</entry>
       <entry>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
         <literal>NegotiateProtocolVersion</literal>. 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 <literal>max_protocol_version=grease</literal>.
       </entry>
       </row>
       <row>
@@ -319,21 +320,40 @@
 
      <tbody>
       <row>
-       <entry><literal>test_protocol_negotiation</literal></entry>
+       <entry><literal>test_protocol_negotiation_XXXX</literal></entry>
        <entry>-</entry>
        <entry>-</entry>
-       <entry>
-        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 <literal>NegotiateProtocolVersion</literal>
-        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.
+       <entry morerows="4">
+        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
+        <literal>NegotiateProtocolVersion</literal> 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 <literal>max_protocol_version=grease</literal>.
        </entry>
       </row>
+      <row>
+       <entry><literal>negotiation_test_XXXX</literal></entry>
+       <entry>-</entry>
+       <entry>-</entry>
+      </row>
+      <row>
+       <entry><literal>protocol_grease_XXXX</literal></entry>
+       <entry>-</entry>
+       <entry>-</entry>
+      </row>
+      <row>
+       <entry><literal>grease_the_server_XXXX</literal></entry>
+       <entry>-</entry>
+       <entry>-</entry>
+      </row>
+      <row>
+       <entry><literal>always_unknown_extension_XXXX</literal></entry>
+       <entry>-</entry>
+       <entry>-</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
-- 
2.52.0