Re: BUG #16486: Prompted password is ignored when password specified in connection string

I wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
>> On Mon, Jun 8, 2020 at 2:36 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> The entire point of the -W switch is that it prompts whether or not
>>> the password is going to be used for anything.

>> A more intuitive interpretation of -W is that it prompts for a password,
>> regardless of valid values being provided by other configuration, and uses
>> that password exclusively to attempt to connect to the server.
>> The documentation doesn't actually say which one of those two
>> interpretations is correct.

> Hmm ... I had thought that the docs explained -W in more or less the same
> way I did above, but I see that (at least on the psql page) things are
> indeed pretty vague.  I'll see about improving that.

Concretely, it looks like we need edits as attached for psql, and
likewise for all our other programs with similar options.

The thing that was really missing here IMO is the specification that a
conninfo string overrides other command-line parameters.  It's somewhat
debatable whether a -W prompt is a "command line parameter", but it
acts that way for this purpose.  In any case, I'm disinclined to document
that specific interaction, because it would amount to blessing a pretty
damfool practice, which is to make your password visible on the program's
command line.  (I wonder whether section 33.1.2 ought to specifically
caution against putting passwords into command-line conninfo strings.)

            regards, tom lane

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 42e862cf17..816406235f 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -177,6 +177,8 @@ EOF
        or <literal>postgres://</literal>), it is treated as a
        <parameter>conninfo</parameter> string. See <xref
        linkend="libpq-connstring"/> for more information.
+       Connection parameters found in the <parameter>conninfo</parameter>
+       string will override other options such as <option>--username</option>.
       </para>
       </listitem>
     </varlistentry>
@@ -498,7 +500,7 @@ EOF
      <listitem>
       <para>
        Never issue a password prompt.  If the server requires password
-       authentication and a password is not available by other means
+       authentication and a password is not available from other sources
        such as a <filename>.pgpass</filename> file, the connection
        attempt will fail.  This option can be useful in batch jobs and
        scripts where no user is present to enter a password.
@@ -518,13 +520,15 @@ EOF
       <listitem>
       <para>
        Force <application>psql</application> to prompt for a
-       password before connecting to a database.
+       password before connecting to a database, even if the password will
+       not be used.
       </para>

       <para>
-       This option is never essential, since <application>psql</application>
-       will automatically prompt for a password if the server demands
-       password authentication.  However, <application>psql</application>
+       If the server requires password authentication and a password is not
+       available from other sources such as a <filename>.pgpass</filename>
+       file, <application>psql</application> will prompt for a
+       password in any case.  However, <application>psql</application>
        will waste a connection attempt finding out that the server wants a
        password.  In some cases it is worth typing <option>-W</option> to avoid
        the extra connection attempt.