From b05751220b0cab7bdf9b729f4fcf6f2adb2d1b46 Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Wed, 2 Apr 2025 16:41:51 +0300 Subject: [PATCH] docs: Add a new section and a table listing protocol versions Move the discussion on protocol versions and version negotiation to a new "Protocol versions" section. Add a table listing all the different protocol versions, starting from the obsolete protocol version 2, and the PostgreSQL versions that support each. Discussion: https://www.postgresql.org/message-id/69f53970-1d55-4165-9151-6fb524e36af9@iki.fi --- doc/src/sgml/protocol.sgml | 104 ++++++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 25 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 4dab0cb4923..d73e4d6dbdf 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -22,31 +22,6 @@ PostgreSQL version 18. The server and the libpq client library are backwards compatible with protocol version 3.0, implemented in PostgreSQL 7.4 and later. - For descriptions of earlier protocol versions, see previous releases of the - PostgreSQL documentation. - - - - A single server - can support multiple protocol versions. The initial startup-request - message tells the server which protocol version the client is attempting to - use. If the major version requested by the client is not supported by - the server, the connection will be rejected (for example, this would occur - if the client requested protocol version 4.0, which does not exist as of - this writing). If the minor version requested by the client is not - supported by the server (e.g., the client requests version 3.2, but the - server supports only 3.0), the server may either reject the connection or - may respond with a NegotiateProtocolVersion message containing the highest - minor protocol version which it supports. The client may then choose either - to continue with the connection using the specified protocol version or - to abort the connection. - - - - The protocol negotiation was introduced in - PostgreSQL version 9.3.21. Earlier versions would - reject the connection if the client requested a minor version that was not - supported by the server. @@ -212,6 +187,85 @@ server versions; the text format is usually the more portable choice. + + + Protocol versions + + + The current, latest version of the protocol is version 3.2. However, for + backwards compatibility with old server versions and middleware that don't + support the version negotiation yet, libpq still uses protocol version 3.0 + by default. + + + + A single server can support multiple protocol versions. The initial + startup-request message tells the server which protocol version the client + is attempting to use. If the major version requested by the client is not + supported by the server, the connection will be rejected (for example, + this would occur if the client requested protocol version 4.0, which does + not exist as of this writing). If the minor version requested by the + client is not supported by the server (e.g., the client requests version + 3.2, but the server supports only 3.0), the server may either reject the + connection or may respond with a NegotiateProtocolVersion message + containing the highest minor protocol version which it supports. The + client may then choose either to continue with the connection using the + specified protocol version or to abort the connection. + + + + The protocol negotiation was introduced in + PostgreSQL version 9.3.21. Earlier versions + would reject the connection if the client requested a minor version that + was not supported by the server. + + + + Protocol versions + + + + + Version + Supported by + Description + + + + + + 3.2 + PostgreSQL 18 and later + Current latest version. The secret key used in query + cancellation was enlarged from 4 bytes to a variable length field. The + BackendKeyData message was changed to accomodate that, and the CancelRequest + message was redefined to have a variable length payload. + + + + 3.1 + - + Reserved. Version 3.1 has not been used by any PostgreSQL + version, but it was skipped because old versions of the popular + pgbouncer application had a bug in the protocol negotiation which made + it incorrectly claim that it supported version 3.1. + + + + 3.0 + PostgreSQL 7.4 and later + + + 2.0 + up to PostgreSQL 13 + See previous releases of + the PostgreSQL documentation for + details + + + +
+ -- 2.39.5