rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: update versioning information in libpq.sgml. 

The descriptions of PQserverVersion and PQlibVersion hadn't been updated
for the new two-part version-numbering approach.  Fix that.

In passing, remove some trailing whitespace elsewhere in the file.
This commit is contained in:
Tom Lane 2017-07-21 17:50:57 -04:00
parent a46fe6e8be
commit e22efaabf1
1 changed files with 63 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
doc/src/sgml/libpq.sgml
View File

@ -892,8 +892,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<title>Specifying Multiple Hosts</title> <title>Specifying Multiple Hosts</title>
<para> <para>
It is possible to specify multiple hosts to connect to, so that they are It is possible to specify multiple hosts to connect to, so that they are
tried in the given order. In the Keyword/Value format, the <literal>host</>, tried in the given order. In the Keyword/Value format, the <literal>host</>,
<literal>hostaddr</>, and <literal>port</> options accept a comma-separated <literal>hostaddr</>, and <literal>port</> options accept a comma-separated
list of values. The same number of elements must be given in each option, such list of values. The same number of elements must be given in each option, such
that e.g. the first <literal>hostaddr</> corresponds to the first host name, that e.g. the first <literal>hostaddr</> corresponds to the first host name,
@ -903,24 +903,24 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</para> </para>
<para> <para>
In the connection URI format, you can list multiple <literal>host:port</> pairs In the connection URI format, you can list multiple <literal>host:port</> pairs
separated by commas, in the <literal>host</> component of the URI. In either separated by commas, in the <literal>host</> component of the URI. In either
format, a single hostname can also translate to multiple network addresses. A format, a single hostname can also translate to multiple network addresses. A
common example of this is a host that has both an IPv4 and an IPv6 address. common example of this is a host that has both an IPv4 and an IPv6 address.
</para> </para>
<para> <para>
When multiple hosts are specified, or when a single hostname is When multiple hosts are specified, or when a single hostname is
translated to multiple addresses, all the hosts and addresses will be translated to multiple addresses, all the hosts and addresses will be
tried in order, until one succeeds. If none of the hosts can be reached, tried in order, until one succeeds. If none of the hosts can be reached,
the connection fails. If a connection is established successfully, but the connection fails. If a connection is established successfully, but
authentication fails, the remaining hosts in the list are not tried. authentication fails, the remaining hosts in the list are not tried.
</para> </para>
<para> <para>
If a password file is used, you can have different passwords for If a password file is used, you can have different passwords for
different hosts. All the other connection options are the same for every different hosts. All the other connection options are the same for every
host, it is not possible to e.g. specify a different username for host, it is not possible to e.g. specify a different username for
different hosts. different hosts.
</para> </para>
</sect3> </sect3>
@ -1844,17 +1844,36 @@ int PQprotocolVersion(const PGconn *conn);
<listitem> <listitem>
<para> <para>
Returns an integer representing the backend version. Returns an integer representing the server version.
<synopsis> <synopsis>
int PQserverVersion(const PGconn *conn); int PQserverVersion(const PGconn *conn);
</synopsis> </synopsis>
Applications might use this function to determine the version of the database </para>
server they are connected to. The number is formed by converting
the major, minor, and revision numbers into two-decimal-digit <para>
numbers and appending them together. For example, version 8.1.5 Applications might use this function to determine the version of the
will be returned as 80105, and version 8.2 will be returned as database server they are connected to. The result is formed by
80200 (leading zeroes are not shown). Zero is returned if the multiplying the server's major version number by 10000 and adding
connection is bad. the minor version number. For example, version 10.1 will be
returned as 100001, and version 11.0 will be returned as 110000.
Zero is returned if the connection is bad.
</para>
<para>
Prior to major version 10, <productname>PostgreSQL</> used
three-part version numbers in which the first two parts together
represented the major version. For those
versions, <function>PQserverVersion</> uses two digits for each
part; for example version 9.1.5 will be returned as 90105, and
version 9.2.0 will be returned as 90200.
</para>
<para>
Therefore, for purposes of determining feature compatibility,
applications should divide the result of <function>PQserverVersion</>
by 100 not 10000 to determine a logical major version number.
In all release series, only the last two digits differ between
minor releases (bug-fix releases).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -6224,26 +6243,42 @@ int PQlibVersion(void);
<para> <para>
The result of this function can be used to determine, at The result of this function can be used to determine, at
run time, if specific functionality is available in the currently run time, whether specific functionality is available in the currently
loaded version of libpq. The function can be used, for example, loaded version of libpq. The function can be used, for example,
to determine which connection options are available for to determine which connection options are available in
<function>PQconnectdb</> or if the <literal>hex</> <type>bytea</> <function>PQconnectdb</>.
output added in PostgreSQL 9.0 is supported.
</para> </para>
<para> <para>
The number is formed by converting the major, minor, and revision The result is formed by multiplying the library's major version
numbers into two-decimal-digit numbers and appending them together. number by 10000 and adding the minor version number. For example,
For example, version 9.1 will be returned as 90100, and version version 10.1 will be returned as 100001, and version 11.0 will be
9.1.2 will be returned as 90102 (leading zeroes are not shown). returned as 110000.
</para>
<para>
Prior to major version 10, <productname>PostgreSQL</> used
three-part version numbers in which the first two parts together
represented the major version. For those
versions, <function>PQlibVersion</> uses two digits for each
part; for example version 9.1.5 will be returned as 90105, and
version 9.2.0 will be returned as 90200.
</para>
<para>
Therefore, for purposes of determining feature compatibility,
applications should divide the result of <function>PQlibVersion</>
by 100 not 10000 to determine a logical major version number.
In all release series, only the last two digits differ between
minor releases (bug-fix releases).
</para> </para>
<note> <note>
<para> <para>
This function appeared in <productname>PostgreSQL</> version 9.1, so This function appeared in <productname>PostgreSQL</> version 9.1, so
it cannot be used to detect required functionality in earlier it cannot be used to detect required functionality in earlier
versions, since linking to it will create a link dependency versions, since calling it will create a link dependency
on version 9.1. on version 9.1 or later.
</para> </para>
</note> </note>
</listitem> </listitem>