diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index c1d1b6b2db..b0f8f5097f 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -964,49 +964,41 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
host
- Name of host to connect to.host name
- If a host name begins with a slash, it specifies Unix-domain
- communication rather than TCP/IP communication; the value is the
- name of the directory in which the socket file is stored.
+ Comma-separated list of hosts to connect to.
+ Each item may be a host namehost name
+ that will be resolved with a look-up,
+ a numeric IP address that will be used directly, or
+ the full path of a directory which contains the socket file for
+ Unix-domain communication rather than TCP/IP communication;
+ Each specified host will be tried in turn in the order given.
+ See for details.
+
+
+
The default behavior when host is
- not specified, or is empty, is to connect to a Unix-domain
+ not specified, or an item is empty, is to connect to a Unix-domain
socketUnix domain socket in
/tmp (or whatever socket directory was specified
- when PostgreSQL was built). On machines without
- Unix-domain sockets, the default is to connect to localhost.
+ when PostgreSQL was built).
+ On machines without Unix-domain sockets, the default is to connect to
+ localhost.
-
- A comma-separated list of host names is also accepted, in which case
- each host name in the list is tried in order; an empty item in the
- list selects the default behavior as explained above. See
- for details.
-
-
-
-
- hostaddr
-
- Numeric IP address of host to connect to. This should be in the
- standard IPv4 address format, e.g., 172.28.40.9. If
- your machine supports IPv6, you can also use those addresses.
- TCP/IP communication is
- always used when a nonempty string is specified for this parameter.
+ To shortcut host name lookups, see parameter
+ .
- Using hostaddr instead of host allows the
- application to avoid a host name look-up, which might be important
- in applications with time constraints. However, a host name is
- required for GSSAPI or SSPI authentication
- methods, as well as for verify-full SSL
- certificate verification. The following rules are used:
+ When connecting, the following rules apply:
- If host is specified
- without hostaddr, a host name lookup occurs.
+ If an item in host has a corresponding empty
+ item in hostaddr, it is used:
+ For an IP address or a Unix-domain socket, it is done directly.
+ For a host name, a lookup occurs, and the resulting set of IPs will
+ be tried in turn.
(When using PQconnectPoll, the lookup occurs
when PQconnectPoll first considers this host
name, and it may cause PQconnectPoll to block
@@ -1015,45 +1007,48 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
- If hostaddr is specified without host,
- the value for hostaddr gives the server network address.
- The connection attempt will fail if the authentication
- method requires a host name.
-
-
-
-
- If both host and hostaddr are specified,
- the value for hostaddr gives the server network address.
- The value for host is ignored unless the
- authentication method requires it, in which case it will be
- used as the host name.
+ If an item in host has a corresponding non-empty
+ item in hostaddr, the later network address is
+ used and the host name may be used for authentication purposes.
- Note that authentication is likely to fail if host
+
+
+
+
+
+ hostaddr
+
+
+ Comma-separated numeric IP addresses corresponding one-to-one to
+ host, to avoid a host name look-up when non empty.
+ This may be desirable for testing, to work around NAT settings, or for
+ better performance.
+
+
+
+ Parameter hostaddr must be either empty or a
+ list of the same length as host.
+ A non empty IP in hostaddr overrides any
+ corresponding item in host.
+
+
+
+ If a host name is required for GSSAPI or SSPI authentication
+ methods, for verify-full SSL certificate
+ verification, or to identify the connection in
+ a password file (see ),
+ the corresponding host name provided by host is used.
+
+
+
+ When both host and hostaddr parameters
+ are set, note that authentication is likely to fail if host
is not the name of the server at network address hostaddr.
- Also, when both host and hostaddr
- are specified, host
- is used to identify the connection in a password file (see
- ).
-
-
- A comma-separated list of hostaddr values is also
- accepted, in which case each host in the list is tried in order.
- An empty item in the list causes the corresponding host name to be
- used, or the default host name if that is empty as well. See
- for details.
-
-
- Without either a host name or host address,
- libpq will connect using a
- local Unix-domain socket; or on machines without Unix-domain
- sockets, it will attempt to connect to localhost.
-
-
-
+
+
port
@@ -1062,10 +1057,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
Port number to connect to at the server host, or socket file
name extension for Unix-domain
connections.port
- If multiple hosts were given in the host or
- hostaddr parameters, this parameter may specify a
- comma-separated list of ports of the same length as the host list, or
- it may specify a single port number to be used for all hosts.
+ If multiple hosts were given in the host parameter,
+ this parameter may specify a comma-separated list of ports of the same
+ length as the host list, or it may specify a single port number to be
+ used for all hosts.
An empty string, or an empty item in a comma-separated list,
specifies the default port number established
when PostgreSQL was built.