diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 82a440531b..e4e8549d8a 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -964,49 +964,43 @@ 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.host name + Each specified host will be tried in turn in the order given. + See for details. + Each item may be a host name that will be resolved with a look-up, + a numeric IP address (IPv4 in the standard format, e.g., + 172.28.40.9, or IPv6 if supported by your machine) + that will be used directly, or + the name of a directory which contains the socket file for Unix-domain + communication rather than TCP/IP communication + (the specification must then begin with a slash); + + + 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 +1009,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 +1059,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.