diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 68 | ||||
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 33 |
2 files changed, 94 insertions, 7 deletions
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index b359fbff295..d7051190320 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -2144,6 +2144,54 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname </listitem> </varlistentry> + <varlistentry id="libpq-connect-min-protocol-version" xreflabel="min_protocol_version"> + <term><literal>min_protocol_version</literal></term> + <listitem> + <para> + Specifies the minimum protocol version to allow for the connection. + The default is to allow any version of the + <productname>PostgreSQL</productname> protocol supported by libpq, + which currently means <literal>3.0</literal>. If the server + does not support at least this protocol version the connection will be + closed. + </para> + + <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>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-max-protocol-version" xreflabel="max_protocol_version"> + <term><literal>max_protocol_version</literal></term> + <listitem> + <para> + Specifies the protocol version to request from the server. + The default is to use version <literal>3.0</literal> of the + <productname>PostgreSQL</productname> protocol, unless the connection + string specifies a feature that relies on a higher protocol version, + in which case the latest version supported by libpq is used. 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 <xref linkend="libpq-PQprotocolVersion"/> to + find out which exact protocol version was negotiated. + </para> + + <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>. + </para> + </listitem> + </varlistentry> + <varlistentry id="libpq-connect-ssl-max-protocol-version" xreflabel="ssl_max_protocol_version"> <term><literal>ssl_max_protocol_version</literal></term> <listitem> @@ -9329,6 +9377,26 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-load-balance-hosts"/> connection parameter. </para> </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGMINPROTOCOLVERSION</envar></primary> + </indexterm> + <envar>PGMINPROTOCOLVERSION</envar> behaves the same as the <xref + linkend="libpq-connect-min-protocol-version"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGMAXPROTOCOLVERSION</envar></primary> + </indexterm> + <envar>PGMAXPROTOCOLVERSION</envar> behaves the same as the <xref + linkend="libpq-connect-max-protocol-version"/> connection parameter. + </para> + </listitem> </itemizedlist> </para> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 6008f3ac5f8..628da4cd7cc 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -18,17 +18,23 @@ </para> <para> - This document describes version 3.0 of the protocol, implemented in - <productname>PostgreSQL</productname> 7.4 and later. For descriptions - of the earlier protocol versions, see previous releases of the - <productname>PostgreSQL</productname> documentation. A single server + This document describes version 3.2 of the protocol, introduced in + <productname>PostgreSQL</productname> version 18. The server and the libpq + client library are backwards compatible with protocol version 3.0, + implemented in <productname>PostgreSQL</productname> 7.4 and later. + For descriptions of earlier protocol versions, see previous releases of the + <productname>PostgreSQL</productname> documentation. + </para> + + <para> + 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.1, but the + 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 @@ -36,6 +42,13 @@ to abort the connection. </para> + <para> + The protocol negotiation was introduced in + <productname>PostgreSQL</productname> version 9.3.21. Earlier versions would + reject the connection if the client requested a minor version that was not + supported by the server. + </para> + <para> In order to serve multiple clients efficiently, the server launches a new <quote>backend</quote> process for each client. @@ -413,8 +426,14 @@ this message indicates the highest supported minor version. This message will also be sent if the client requested unsupported protocol options (i.e., beginning with <literal>_pq_.</literal>) in the - startup packet. This message will be followed by an ErrorResponse or - a message indicating the success or failure of authentication. + startup packet. + </para> + <para> + After this message, the authentication will continue using the version + indicated by the server. If the client does not support the older + version, it should immediately close the connection. If the server + does not send this message, it supports the client's requested + protocol version and all the protocol options. </para> </listitem> </varlistentry> |