doc: libpq connection options can override command-line flags

Reported-by: Alexander Lakhin
Discussion: https://postgr.es/m/16486-b9c93d71c02c4907@postgresql.org

Backpatch-through: 9.5

diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index c13d74853ebbee33d8f277195f3ef31e7d69bd49..8e4f9c9cbbff3099efb421b4114153cb4a00ad8f 100644 (file)
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -95,7 +95,10 @@ PostgreSQL documentation
         <option>--all</option>) is not used, the database name is read
         from the environment variable <envar>PGDATABASE</envar>.  If
         that is not set, the user name specified for the connection is
-        used.
+        used.  The <replaceable>dbname</replaceable> can be a <link
+        linkend="libpq-connstring">connection string</link>.  If so,
+        connection string parameters will override any conflicting command
+        line options.
        </para>
       </listitem>
      </varlistentry>

diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 134b29823683269ff1edf4508253349a9ba5c624..390e860240ddaaf1033217709f33a5f73a0283b6 100644 (file)
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -444,8 +444,9 @@ PostgreSQL documentation
       <term><option>--dbname=<replaceable class="parameter">connstr</replaceable></option></term>
       <listitem>
        <para>
-        Specifies parameters used to connect to the server, as a connection
-        string. See <xref linkend="libpq-connstring"> for more information.
+        Specifies parameters used to connect to the server, as a <link
+        linkend="libpq-connstring">connction string</link>;  these
+        will override any conflicting command line options.
        </para>
        <para>
         The option is called <literal>--dbname</> for consistency with other

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 659cdd77aa0d931ad3ef62e624fcd80d4fda5473..ee5b9dc12cee93ef25d811b9410db38ebbcdb0e2 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -979,14 +979,10 @@ PostgreSQL documentation
        Specifies the name of the database to connect to. This is
        equivalent to specifying <replaceable
        class="parameter">dbname</replaceable> as the first non-option
-       argument on the command line.
-      </para>
-      <para>
-       If this parameter contains an <symbol>=</symbol> sign or starts
-       with a valid <acronym>URI</acronym> prefix
-       (<literal>postgresql://</literal>
-       or <literal>postgres://</literal>), it is treated as a
-       <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
+       argument on the command line.  The <replaceable>dbname</replaceable>
+       can be a <link linkend="libpq-connstring">connection string</link>.
+       If so, connection string parameters will override any conflicting
+       command line options.
       </para>
       </listitem>
      </varlistentry>

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 10c74427b17ae49b3f441b7147d443075391a29f..ef2f422e0b033ad04407c2b2ea9a56d5b6c29b63 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -419,8 +419,9 @@ PostgreSQL documentation
       <term><option>--dbname=<replaceable class="parameter">connstr</replaceable></option></term>
       <listitem>
        <para>
-        Specifies parameters used to connect to the server, as a connection
-        string. See <xref linkend="libpq-connstring"> for more information.
+        Specifies parameters used to connect to the server, as a <link
+        linkend="libpq-connstring">connction string</link>;  these
+        will override any conflicting command line options.
        </para>
        <para>
         The option is called <literal>--dbname</> for consistency with other

diff --git a/doc/src/sgml/ref/pg_isready.sgml b/doc/src/sgml/ref/pg_isready.sgml
index 2ee79a0bbebb46b4d4287776868cded24fc9b710..f966d0feed459bc05190fb70136967e77a3b63f8 100644 (file)
--- a/doc/src/sgml/ref/pg_isready.sgml
+++ b/doc/src/sgml/ref/pg_isready.sgml
@@ -47,15 +47,11 @@ PostgreSQL documentation
       <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term>
       <listitem>
       <para>
-       Specifies the name of the database to connect to.
-      </para>
-      <para>
-       If this parameter contains an <symbol>=</symbol> sign or starts
-       with a valid <acronym>URI</acronym> prefix
-       (<literal>postgresql://</literal>
-       or <literal>postgres://</literal>), it is treated as a
-       <parameter>conninfo</parameter> string. See <xref
-       linkend="libpq-connstring"> for more information.
+       Specifies the name of the database to connect to. The
+       <replaceable>dbname</replaceable> can be a <link
+       linkend="libpq-connstring">connection string</link>.  If so,
+       connection string parameters will override any conflicting command
+       line options.
       </para>
       </listitem>
     </varlistentry>

diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index b35881f2b9eca9e614a1ad4f940609b54f1727d1..3751863cefd94ac7a89719b02004b269604b7e1a 100644 (file)
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -239,14 +239,16 @@ PostgreSQL documentation
 
     <variablelist>
       <varlistentry>
-       <term><option>-d <replaceable>database</replaceable></option></term>
-       <term><option>--dbname=<replaceable>database</replaceable></option></term>
+       <term><option>-d <replaceable>dbname</replaceable></option></term>
+       <term><option>--dbname=<replaceable>dbname</replaceable></option></term>
        <listitem>
         <para>
-         The database to connect to.  See the description of the actions for
-         what this means in detail.  This can be a <application>libpq</application> connection string;
-         see <xref linkend="LIBPQ-CONNSTRING"> for more information.  Defaults
-         to user name.
+         The database to connect to.  See the description
+         of the actions for what this means in detail.
+         The <replaceable>dbname</replaceable> can be a <link
+         linkend="libpq-connstring">connection string</link>.  If so,
+         connection string parameters will override any conflicting
+         command line options.  Defaults to the user name.
         </para>
        </listitem>
       </varlistentry>

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 3c23d1c0b0c2f47fedf97eae0f9b7e9ad91318fd..71a8d012020a9a0466c776b29071018782a5a279 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -145,7 +145,10 @@ PostgreSQL documentation
        <para>
         Connect to database <replaceable
         class="parameter">dbname</replaceable> and restore directly
-        into the database.
+        into the database.  The <replaceable>dbname</replaceable> can
+        be a <link linkend="libpq-connstring">connection string</link>.
+        If so, connection string parameters will override any conflicting
+        command line options.
        </para>
       </listitem>
      </varlistentry>

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 858e3c5ff55708194e79b9d32c146410a9b6eb2a..2f944b1e9754efde3c79c816aac074d7c2feed36 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -156,15 +156,10 @@ EOF
        Specifies the name of the database to connect to. This is
        equivalent to specifying <replaceable
        class="parameter">dbname</replaceable> as the first non-option
-       argument on the command line.
-      </para>
-      <para>
-       If this parameter contains an <symbol>=</symbol> sign or starts
-       with a valid <acronym>URI</acronym> prefix
-       (<literal>postgresql://</literal>
-       or <literal>postgres://</literal>), it is treated as a
-       <parameter>conninfo</parameter> string. See <xref
-       linkend="libpq-connstring"> for more information.
+       argument on the command line.  The <replaceable>dbname</replaceable>
+       can be a <link linkend="libpq-connstring">connection string</link>.
+       If so, connection string parameters will override any conflicting
+       command line options.
       </para>
       </listitem>
     </varlistentry>
@@ -477,7 +472,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.
@@ -497,13 +492,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</> to avoid
        the extra connection attempt.

diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 713efc099be946d95ad52676137737340e47a25e..2f4b4618edcabf4f82d1659f7cc22d6dff84c186 100644 (file)
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -128,7 +128,10 @@ PostgreSQL documentation
         <option>--all</option>) is not used, the database name is read
         from the environment variable <envar>PGDATABASE</envar>.  If
         that is not set, the user name specified for the connection is
-        used.
+        used.  The <replaceable>dbname</replaceable> can be a <link
+        linkend="libpq-connstring">connection string</link>.  If so,
+        connection string parameters will override any conflicting command
+        line options.
        </para>
       </listitem>
      </varlistentry>

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 92b8984b7a6a9db9756ab2176b69841f06485e72..f8e2e1a9447ed49e00d94e96d66b9eca09217a5f 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -97,7 +97,10 @@ PostgreSQL documentation
         <option>--all</option>) is not used, the database name is read
         from the environment variable <envar>PGDATABASE</envar>.  If
         that is not set, the user name specified for the connection is
-        used.
+        used.  The <replaceable>dbname</replaceable> can be a <link
+        linkend="libpq-connstring">connection string</link>.  If so,
+        connection string parameters will override any conflicting command
+        line options.
        </para>
       </listitem>
      </varlistentry>