Re: libpq host/hostaddr/conninfo inconsistencies

Hello.

At Thu, 14 Feb 2019 22:51:40 +0100 (CET), Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> wrote in <alpine(dot)DEB(dot)2(dot)21(dot)1902142224380(dot)20189(at)lancre>
>
> > On 2018-10-26 09:21:51 +0200, Fabien COELHO wrote:
> >> (1) you are somehow against changing the current implementation, eg
> >> erroring
> >> out on possibly misleading configurations, because you do not think it
> >> is
> >> really useful to help users in those cases.
> >
> > I find this formulation somewhat passive aggressive.
>
> I do not understand what you mean by that expression.
>
> I was just trying to sum-up Robert's opposition to erroring on
> misleading configurations (eg "host=1.2.3.4 hostaddr=4.3.2.1") instead
> of complying to it whatever, as is currently done. Probably my
> phrasing could be improved, but I do not think that I misrepresented
> Robert's position.
>
> Note that the issue is somehow mitigated by 6e5f8d489a: \conninfo now
> displays a more precise information, so that at least you are not told
> that you are connected to a socket when you a really connected to an
> ip, or to one ip when you a really connected to another.

I'm rather on (maybe) Robert's side in that not opposing to edit
it but documentation should be plain as far as it is not so
mis-leading for average readers. From the same viewpoint,
documentation is written general-and-important-first, then
special cases and trivials.

On such standpoint, the first hunk in the patch attracted my
eyes.

<term><literal>host</literal></term>
<listitem>
<para>
- Name of host to connect to.<indexterm><primary>host name</primary></indexterm>
- 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.<indexterm><primary>host name</primary></indexterm>
+ Each specified host will be tried in turn in the order given.
+ See <xref linkend="libpq-multiple-hosts"/> 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.,
+ <literal>172.28.40.9</literal>, 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);
+ </para>

I don't think this is user-friendly since almost all of them
don't write multiple hosts there. So I prefer the previous
organization. The description about IP-address looks too verbose,
especially we don't need explain what is IP-address here.

regards.

--
Kyotaro Horiguchi
NTT Open Source Software Center