@@ -123,35 +123,53 @@ PGconn *PQconnectdbParams(const char * const *keywords,
123123 </para>
124124
125125 <para>
126- When <literal>expand_dbname</literal> is non-zero, the
127- <parameter>dbname</parameter> key word value is allowed to be recognized
128- as a connection string. Only the first occurrence of
129- <parameter>dbname</parameter> is expanded this way, any subsequent
130- <parameter>dbname</parameter> value is processed as plain database name. More
131- details on the possible connection string formats appear in
132- <xref linkend="libpq-connstring"/>.
126+ The passed arrays can be empty to use all default parameters, or can
127+ contain one or more parameter settings. They must be matched in length.
128+ Processing will stop at the first <symbol>NULL</symbol> entry
129+ in the <literal>keywords</literal> array.
130+ Also, if the <literal>values</literal> entry associated with a
131+ non-<symbol>NULL</symbol> <literal>keywords</literal> entry is
132+ <symbol>NULL</symbol> or an empty string, that entry is ignored and
133+ processing continues with the next pair of array entries.
133134 </para>
134135
135136 <para>
136- The passed arrays can be empty to use all default parameters, or can
137- contain one or more parameter settings. They should be matched in length.
138- Processing will stop at the first <symbol>NULL</symbol> element
139- in the <literal>keywords</literal> array.
137+ When <literal>expand_dbname</literal> is non-zero, the value for
138+ the first <parameter>dbname</parameter> key word is checked to see
139+ if it is a <firstterm>connection string</firstterm>. If so, it
140+ is <quote>expanded</quote> into the individual connection
141+ parameters extracted from the string. The value is considered to
142+ be a connection string, rather than just a database name, if it
143+ contains an equal sign (<literal>=</literal>) or it begins with a
144+ URI scheme designator. (More details on connection string formats
145+ appear in <xref linkend="libpq-connstring"/>.) Only the first
146+ occurrence of <parameter>dbname</parameter> is treated in this way;
147+ any subsequent <parameter>dbname</parameter> parameter is processed
148+ as a plain database name.
140149 </para>
141150
142151 <para>
143- If any parameter is <symbol>NULL</symbol> or an empty string, the corresponding
144- environment variable (see <xref linkend="libpq-envars"/>) is checked.
145- If the environment variable is not set either, then the indicated
146- built-in defaults are used.
152+ In general the parameter arrays are processed from start to end.
153+ If any key word is repeated, the last value (that is
154+ not <symbol>NULL</symbol> or empty) is used. This rule applies in
155+ particular when a key word found in a connection string conflicts
156+ with one appearing in the <literal>keywords</literal> array. Thus,
157+ the programmer may determine whether array entries can override or
158+ be overridden by values taken from a connection string. Array
159+ entries appearing before an expanded <parameter>dbname</parameter>
160+ entry can be overridden by fields of the connection string, and in
161+ turn those fields are overridden by array entries appearing
162+ after <parameter>dbname</parameter> (but, again, only if those
163+ entries supply non-empty values).
147164 </para>
148165
149166 <para>
150- In general key words are processed from the beginning of these arrays in index
151- order. The effect of this is that when key words are repeated, the last processed
152- value is retained. Therefore, through careful placement of the
153- <parameter>dbname</parameter> key word, it is possible to determine what may
154- be overridden by a <parameter>conninfo</parameter> string, and what may not.
167+ After processing all the array entries and any expanded connection
168+ string, any connection parameters that remain unset are filled with
169+ default values. If an unset parameter's corresponding environment
170+ variable (see <xref linkend="libpq-envars"/>) is set, its value is
171+ used. If the environment variable is not set either, then the
172+ parameter's built-in default value is used.
155173 </para>
156174
157175 </listitem>
@@ -886,15 +904,15 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
886904 <para>
887905 The general form for a connection <acronym>URI</acronym> is:
888906<synopsis>
889- postgresql://[user[:password]@][netloc ][:port][,...][/dbname][?param1=value1&...]
907+ postgresql://[user[:password]@][host ][:port][,...][/dbname][?param1=value1&...]
890908</synopsis>
891909 </para>
892910
893911 <para>
894912 The <acronym>URI</acronym> scheme designator can be either
895913 <literal>postgresql://</literal> or <literal>postgres://</literal>. Each
896- of the <acronym>URI</acronym> parts is optional. The following examples
897- illustrate valid <acronym>URI</acronym> syntax uses :
914+ of the
remaining <acronym>URI</acronym> parts is optional. The
915+ following examples illustrate valid <acronym>URI</acronym> syntax:
898916<programlisting>
899917postgresql://
900918postgresql://localhost
@@ -905,11 +923,17 @@ postgresql://user:secret@localhost
905923postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
906924postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
907925</programlisting>
908- Components of the hierarchical part of the <acronym>URI</acronym> can also
909- be given as parameters. For example:
926+ Values that would normally appear in the hierarchical part of
927+ the <acronym>URI</acronym> can alternatively be given as named
928+ parameters. For example:
910929<programlisting>
911930postgresql:///mydb?host=localhost&port=5433
912931</programlisting>
932+ All named parameters must match key words listed in
933+ <xref linkend="libpq-paramkeywords"/>, except that for compatibility
934+ with JDBC connection <acronym>URI</acronym>s, instances
935+ of <literal>ssl=true</literal> are translated into
936+ <literal>sslmode=require</literal>.
913937 </para>
914938
915939 <para>
@@ -925,35 +949,23 @@ postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
925949 </para>
926950
927951 <para>
928- Any connection parameters not corresponding to key words listed in <xref
929- linkend="libpq-paramkeywords"/> are ignored and a warning message about them
930- is sent to <filename>stderr</filename>.
931- </para>
932-
933- <para>
934- For improved compatibility with JDBC connection <acronym>URI</acronym>s,
935- instances of parameter <literal>ssl=true</literal> are translated into
936- <literal>sslmode=require</literal>.
937- </para>
938-
939- <para>
940- The host part may be either host name or an IP address. To specify an
941- IPv6 host address, enclose it in square brackets:
952+ The host part may be either a host name or an IP address. To specify an
953+ IPv6 address, enclose it in square brackets:
942954<synopsis>
943955postgresql://[2001:db8::1234]/database
944956</synopsis>
945957 </para>
946958
947959 <para>
948- The hostcomponent is interpreted as described for the parameter <xref
960+ The hostpart is interpreted as described for the parameter <xref
949961 linkend="libpq-connect-host"/>. In particular, a Unix-domain socket
950962 connection is chosen if the host part is either empty or looks like an
951963 absolute path name,
952964 otherwise a TCP/IP connection is initiated. Note, however, that the
953965 slash is a reserved character in the hierarchical part of the URI. So, to
954966 specify a non-standard Unix-domain socket directory, either omit the host
955- specification in the URI and specify the host as a parameter, or
956- percent-encode the path in the hostcomponent of the URI:
967+ part of the URI and specify the host as a named parameter, or
968+ percent-encode the path in the hostpart of the URI:
957969<programlisting>
958970postgresql:///dbname?host=/var/lib/postgresql
959971postgresql://%2Fvar%2Flib%2Fpostgresql/dbname