Skip to content

Commit 414fb25

Browse files
tglsfdctglsfdc
committed
Doc: clarify behavior of PQconnectdbParams().
The documentation omitted the critical tidbit that a keyword-array entry is simply ignored if its corresponding value-array entry is NULL or an empty string; it will *not* override any previously-obtained value for the parameter. (See conninfo_array_parse().) I'd supposed that would force the setting back to default, which is what led me into bug #16746; but it doesn't. While here, I couldn't resist the temptation to do some copy-editing, both in the description of PQconnectdbParams() and in the section about connection URI syntax. Discussion: https://postgr.es/m/931505.1606618746@sss.pgh.pa.us
1 parent 60d6c71 commit 414fb25

File tree

1 file changed

+57
-44
lines changed

1 file changed

+57
-44
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 57 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -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>
@@ -793,15 +811,15 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
793811
<para>
794812
The general form for a connection <acronym>URI</acronym> is:
795813
<synopsis>
796-
postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&amp;...]
814+
postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&amp;...]
797815
</synopsis>
798816
</para>
799817

800818
<para>
801819
The <acronym>URI</acronym> scheme designator can be either
802820
<literal>postgresql://</literal> or <literal>postgres://</literal>. Each
803-
of the <acronym>URI</acronym> parts is optional. The following examples
804-
illustrate valid <acronym>URI</acronym> syntax uses:
821+
of the remaining <acronym>URI</acronym> parts is optional. The
822+
following examples illustrate valid <acronym>URI</acronym> syntax:
805823
<programlisting>
806824
postgresql://
807825
postgresql://localhost
@@ -811,11 +829,17 @@ postgresql://user@localhost
811829
postgresql://user:secret@localhost
812830
postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
813831
</programlisting>
814-
Components of the hierarchical part of the <acronym>URI</acronym> can also
815-
be given as parameters. For example:
832+
Values that would normally appear in the hierarchical part of
833+
the <acronym>URI</acronym> can alternatively be given as named
834+
parameters. For example:
816835
<programlisting>
817836
postgresql:///mydb?host=localhost&amp;port=5433
818837
</programlisting>
838+
All named parameters must match key words listed in
839+
<xref linkend="libpq-paramkeywords">, except that for compatibility
840+
with JDBC connection <acronym>URI</acronym>s, instances
841+
of <literal>ssl=true</literal> are translated into
842+
<literal>sslmode=require</literal>.
819843
</para>
820844

821845
<para>
@@ -824,34 +848,23 @@ postgresql:///mydb?host=localhost&amp;port=5433
824848
</para>
825849

826850
<para>
827-
Any connection parameters not corresponding to key words listed in <xref
828-
linkend="libpq-paramkeywords"> are ignored and a warning message about them
829-
is sent to <filename>stderr</filename>.
830-
</para>
831-
832-
<para>
833-
For improved compatibility with JDBC connection <acronym>URI</acronym>s,
834-
instances of parameter <literal>ssl=true</literal> are translated into
835-
<literal>sslmode=require</literal>.
836-
</para>
837-
838-
<para>
839-
The host part may be either host name or an IP address. To specify an
840-
IPv6 host address, enclose it in square brackets:
851+
The host part may be either a host name or an IP address. To specify an
852+
IPv6 address, enclose it in square brackets:
841853
<synopsis>
842854
postgresql://[2001:db8::1234]/database
843855
</synopsis>
844856
</para>
845857

846858
<para>
847-
The host component is interpreted as described for the parameter <xref
859+
The host part is interpreted as described for the parameter <xref
848860
linkend="libpq-connect-host">. In particular, a Unix-domain socket
849-
connection is chosen if the host part is either empty or starts with a
850-
slash, otherwise a TCP/IP connection is initiated. Note, however, that the
861+
connection is chosen if the host part is either empty or looks like an
862+
absolute path name,
863+
otherwise a TCP/IP connection is initiated. Note, however, that the
851864
slash is a reserved character in the hierarchical part of the URI. So, to
852865
specify a non-standard Unix-domain socket directory, either omit the host
853-
specification in the URI and specify the host as a parameter, or
854-
percent-encode the path in the host component of the URI:
866+
part of the URI and specify the host as a named parameter, or
867+
percent-encode the path in the host part of the URI:
855868
<programlisting>
856869
postgresql:///dbname?host=/var/lib/postgresql
857870
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

0 commit comments

Comments
 (0)