From f419a82c704ec33fe5b861f914935b233a54bcee Mon Sep 17 00:00:00 2001
From: Joe Conway <mail@joeconway.com>
Date: Fri, 5 Feb 2010 03:09:05 +0000
Subject: Modify recently added PQconnectdbParams() with new argument,
 expand_dbname. If expand_dbname is non-zero and dbname contains an = sign, it
 is taken as a conninfo string in exactly the same way as if it had been
 passed to PQconnectdb. This is equivalent to the way PQsetdbLogin() works,
 allowing PQconnectdbParams() to be a complete alternative.

Also improve the way the new function is called from psql and replace a
previously missed call to PQsetdbLogin() in psql. Additionally use
PQconnectdbParams() for pg_dump and friends, and the bin/scripts
command line utilities such as vacuumdb, createdb, etc.

Finally, update the documentation for the new parameter, as well as the
nuances of precedence in cases where key words are repeated or duplicated
in the conninfo string.
---
 doc/src/sgml/libpq.sgml | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index a698ab1958d..c7131fea4c4 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.296 2010/01/28 06:28:26 joe Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.297 2010/02/05 03:09:04 joe Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -98,7 +98,7 @@
        Makes a new connection to the database server.
 
        <synopsis>
-        PGconn *PQconnectdbParams(const char **keywords, const char **values);
+        PGconn *PQconnectdbParams(const char **keywords, const char **values, int expand_dbname);
        </synopsis>
       </para>
 
@@ -114,6 +114,12 @@
        programming.
       </para>
 
+      <para>
+       When <literal>expand_dbname</literal> is non-zero, the
+       <parameter>dbname</parameter> key word value is allowed to be recognized
+       as a <parameter>conninfo</parameter> string. See below for details.
+      </para>
+
       <para>
        The passed arrays can be empty to use all default parameters, or can
        contain one or more parameter settings. They should be matched in length.
@@ -473,6 +479,24 @@
        is checked. If the  environment  variable is not set either,
        then the indicated built-in defaults are used.
       </para>
+
+      <para>
+        If <literal>expand_dbname</literal> is non-zero and 
+        <parameter>dbname</parameter> contains an <symbol>=</symbol> sign, it
+        is taken as a <parameter>conninfo</parameter> string in exactly the same way as
+        if it had been passed to <function>PQconnectdb</function>(see below). Previously
+        processed key words will be overridden by key words in the
+        <parameter>conninfo</parameter> string.
+      </para>
+
+      <para>
+        In general key words are processed from the beginning of these arrays in index
+        order. The effect of this is that when key words are repeated, the last processed
+        value is retained. Therefore, through careful placement of the
+        <parameter>dbname</parameter> key word, it is possible to determine what may
+        be overridden by a <parameter>conninfo</parameter> string, and what may not.
+      </para>
+
      </listitem>
     </varlistentry>
 
@@ -573,7 +597,7 @@ PGconn *PQsetdb(char *pghost,
        Make a connection to the database server in a nonblocking manner.
 
        <synopsis>
-        PGconn *PQconnectStartParams(const char **keywords, const char **values);
+        PGconn *PQconnectStartParams(const char **keywords, const char **values, int expand_dbname);
        </synopsis>
 
        <synopsis>
@@ -597,8 +621,8 @@ PGconn *PQsetdb(char *pghost,
       <para>
        With <function>PQconnectStartParams</function>, the database connection is made
        using the parameters taken from the <literal>keywords</literal> and
-       <literal>values</literal> arrays, as described above for
-       <function>PQconnectdbParams</function>.
+       <literal>values</literal> arrays, and controlled by <literal>expand_dbname</literal>,
+       as described above for <function>PQconnectdbParams</function>.
       </para>
 
       <para>
-- 
cgit v1.2.3