@@ -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>
@@ -887,15 +905,15 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
887905 <para>
888906 The general form for a connection <acronym>URI</acronym> is:
889907<synopsis>
890- postgresql://[user[:password]@][netloc ][:port][,...][/dbname][?param1=value1&...]
908+ postgresql://[user[:password]@][host ][:port][,...][/dbname][?param1=value1&...]
891909</synopsis>
892910 </para>
893911
894912 <para>
895913 The <acronym>URI</acronym> scheme designator can be either
896914 <literal>postgresql://</literal> or <literal>postgres://</literal>. Each
897- of the <acronym>URI</acronym> parts is optional. The following examples
898- illustrate valid <acronym>URI</acronym> syntax uses :
915+ of the
remaining <acronym>URI</acronym> parts is optional. The
916+ following examples illustrate valid <acronym>URI</acronym> syntax:
899917<programlisting>
900918postgresql://
901919postgresql://localhost
@@ -906,11 +924,17 @@ postgresql://user:secret@localhost
906924postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
907925postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
908926</programlisting>
909- Components of the hierarchical part of the <acronym>URI</acronym> can also
910- be given as parameters. For example:
927+ Values that would normally appear in the hierarchical part of
928+ the <acronym>URI</acronym> can alternatively be given as named
929+ parameters. For example:
911930<programlisting>
912931postgresql:///mydb?host=localhost&port=5433
913932</programlisting>
933+ All named parameters must match key words listed in
934+ <xref linkend="libpq-paramkeywords"/>, except that for compatibility
935+ with JDBC connection <acronym>URI</acronym>s, instances
936+ of <literal>ssl=true</literal> are translated into
937+ <literal>sslmode=require</literal>.
914938 </para>
915939
916940 <para>
@@ -926,35 +950,23 @@ postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
926950 </para>
927951
928952 <para>
929- Any connection parameters not corresponding to key words listed in <xref
930- linkend="libpq-paramkeywords"/> are ignored and a warning message about them
931- is sent to <filename>stderr</filename>.
932- </para>
933-
934- <para>
935- For improved compatibility with JDBC connection <acronym>URI</acronym>s,
936- instances of parameter <literal>ssl=true</literal> are translated into
937- <literal>sslmode=require</literal>.
938- </para>
939-
940- <para>
941- The host part may be either host name or an IP address. To specify an
942- IPv6 host address, enclose it in square brackets:
953+ The host part may be either a host name or an IP address. To specify an
954+ IPv6 address, enclose it in square brackets:
943955<synopsis>
944956postgresql://[2001:db8::1234]/database
945957</synopsis>
946958 </para>
947959
948960 <para>
949- The hostcomponent is interpreted as described for the parameter <xref
961+ The hostpart is interpreted as described for the parameter <xref
950962 linkend="libpq-connect-host"/>. In particular, a Unix-domain socket
951963 connection is chosen if the host part is either empty or looks like an
952964 absolute path name,
953965 otherwise a TCP/IP connection is initiated. Note, however, that the
954966 slash is a reserved character in the hierarchical part of the URI. So, to
955967 specify a non-standard Unix-domain socket directory, either omit the host
956- specification in the URI and specify the host as a parameter, or
957- percent-encode the path in the hostcomponent of the URI:
968+ part of the URI and specify the host as a named parameter, or
969+ percent-encode the path in the hostpart of the URI:
958970<programlisting>
959971postgresql:///dbname?host=/var/lib/postgresql
960972postgresql://%2Fvar%2Flib%2Fpostgresql/dbname