Skip to content

Commit 5ca0077

Browse files
tglsfdctglsfdc
committed
In libpq, don't look up all the hostnames at once.
Historically, we looked up the target hostname in connectDBStart, so that PQconnectPoll did not need to do DNS name resolution. The patches that added multiple-target-host support to libpq preserved this division of labor; but it's really nonsensical now, because it means that if any one of the target hosts fails to resolve in DNS, the connection fails. That negates the no-single-point-of-failure goal of the feature. Additionally, DNS lookups aren't exactly cheap, but the code did them all even if the first connection attempt succeeds. Hence, rearrange so that PQconnectPoll does the lookups, and only looks up a hostname when it's time to try that host. This does mean that PQconnectPoll could block on a DNS lookup --- but if you wanted to avoid that, you should be using hostaddr, as the documentation has always specified. It seems fairly unlikely that any applications would really care whether the lookup occurs inside PQconnectStart or PQconnectPoll. In addition to calling out that fact explicitly, do some other minor wordsmithing in the docs around the multiple-target-host feature. Since this seems like a bug in the multiple-target-host feature, backpatch to v10 where that was introduced. In the back branches, avoid moving any existing fields of struct pg_conn, just in case any third-party code is looking into that struct. Tom Lane, reviewed by Fabien Coelho Discussion: https://postgr.es/m/4913.1533827102@sss.pgh.pa.us
1 parent 2d41d91 commit 5ca0077

File tree

3 files changed

+164
-168
lines changed

3 files changed

+164
-168
lines changed

‎doc/src/sgml/libpq.sgml

+45-33
Original file line numberDiff line numberDiff line change
@@ -303,9 +303,9 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
303303
<itemizedlist>
304304
<listitem>
305305
<para>
306-
The <literal>hostaddr</literal> and <literal>host</literal> parameters are used appropriately to ensure that
307-
name and reverse name queries are not made. See the documentation of
308-
these parameters in <xref linkend="libpq-paramkeywords"/> for details.
306+
The <literal>hostaddr</literal> parameter must be used appropriately
307+
to prevent DNS queries from being made. See the documentation of
308+
this parameter in <xref linkend="libpq-paramkeywords"/> for details.
309309
</para>
310310
</listitem>
311311

@@ -318,32 +318,35 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
318318

319319
<listitem>
320320
<para>
321-
You ensure that the socket is in the appropriate state
321+
You must ensure that the socket is in the appropriate state
322322
before calling <function>PQconnectPoll</function>, as described below.
323323
</para>
324324
</listitem>
325325
</itemizedlist>
326326
</para>
327327

328328
<para>
329-
Note: use of <function>PQconnectStartParams</function> is analogous to
330-
<function>PQconnectStart</function> shown below.
329+
To begin a nonblocking connection request,
330+
call <function>PQconnectStart</function>
331+
or <function>PQconnectStartParams</function>. If the result is null,
332+
then <application>libpq</application> has been unable to allocate a
333+
new <structname>PGconn</structname> structure. Otherwise, a
334+
valid <structname>PGconn</structname> pointer is returned (though not
335+
yet representing a valid connection to the database). Next
336+
call <literal>PQstatus(conn)</literal>. If the result
337+
is <symbol>CONNECTION_BAD</symbol>, the connection attempt has already
338+
failed, typically because of invalid connection parameters.
331339
</para>
332340

333341
<para>
334-
To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</replaceable>")</literal>.
335-
If <varname>conn</varname> is null, then <application>libpq</application> has been unable to allocate a new <structname>PGconn</structname>
336-
structure. Otherwise, a valid <structname>PGconn</structname> pointer is returned (though not yet
337-
representing a valid connection to the database). On return from
338-
<function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
339-
<symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
340-
</para>
341-
342-
<para>
343-
If <function>PQconnectStart</function> succeeds, the next stage is to poll
344-
<application>libpq</application> so that it can proceed with the connection sequence.
342+
If <function>PQconnectStart</function>
343+
or <function>PQconnectStartParams</function> succeeds, the next stage
344+
is to poll <application>libpq</application> so that it can proceed with
345+
the connection sequence.
345346
Use <function>PQsocket(conn)</function> to obtain the descriptor of the
346347
socket underlying the database connection.
348+
(Caution: do not assume that the socket remains the same
349+
across <function>PQconnectPoll</function> calls.)
347350
Loop thus: If <function>PQconnectPoll(conn)</function> last returned
348351
<symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
349352
read (as indicated by <function>select()</function>, <function>poll()</function>, or
@@ -352,9 +355,8 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
352355
Conversely, if <function>PQconnectPoll(conn)</function> last returned
353356
<symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
354357
to write, then call <function>PQconnectPoll(conn)</function> again.
355-
If you have yet to call
356-
<function>PQconnectPoll</function>, i.e., just after the call to
357-
<function>PQconnectStart</function>, behave as if it last returned
358+
On the first iteration, i.e. if you have yet to call
359+
<function>PQconnectPoll</function>, behave as if it last returned
358360
<symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until
359361
<function>PQconnectPoll(conn)</function> returns
360362
<symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
@@ -479,10 +481,12 @@ switch(PQstatus(conn))
479481
</para>
480482

481483
<para>
482-
Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
483-
<function>PQfinish</function> when you are finished with it, in order to dispose of
484-
the structure and any associated memory blocks. This must be done even if
485-
the connection attempt fails or is abandoned.
484+
Note that when <function>PQconnectStart</function>
485+
or <function>PQconnectStartParams</function> returns a non-null
486+
pointer, you must call <function>PQfinish</function> when you are
487+
finished with it, in order to dispose of the structure and any
488+
associated memory blocks. This must be done even if the connection
489+
attempt fails or is abandoned.
486490
</para>
487491
</listitem>
488492
</varlistentry>
@@ -913,7 +917,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
913917
It is possible to specify multiple hosts to connect to, so that they are
914918
tried in the given order. In the Keyword/Value format, the <literal>host</literal>,
915919
<literal>hostaddr</literal>, and <literal>port</literal> options accept a comma-separated
916-
list of values. The same number of elements must be given in each option, such
920+
list of values. The same number of elements must be given in each
921+
option that is specified, such
917922
that e.g. the first <literal>hostaddr</literal> corresponds to the first host name,
918923
the second <literal>hostaddr</literal> corresponds to the second host name, and so
919924
forth. As an exception, if only one <literal>port</literal> is specified, it
@@ -922,9 +927,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
922927

923928
<para>
924929
In the connection URI format, you can list multiple <literal>host:port</literal> pairs
925-
separated by commas, in the <literal>host</literal> component of the URI. In either
926-
format, a single host name can also translate to multiple network addresses. A
927-
common example of this is a host that has both an IPv4 and an IPv6 address.
930+
separated by commas, in the <literal>host</literal> component of the URI.
931+
</para>
932+
933+
<para>
934+
In either format, a single host name can translate to multiple network
935+
addresses. A common example of this is a host that has both an IPv4 and
936+
an IPv6 address.
928937
</para>
929938

930939
<para>
@@ -958,9 +967,8 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
958967
Name of host to connect to.<indexterm><primary>host name</primary></indexterm>
959968
If a host name begins with a slash, it specifies Unix-domain
960969
communication rather than TCP/IP communication; the value is the
961-
name of the directory in which the socket file is stored. If
962-
multiple host names are specified, each will be tried in turn in
963-
the order given. The default behavior when <literal>host</literal> is
970+
name of the directory in which the socket file is stored.
971+
The default behavior when <literal>host</literal> is
964972
not specified, or is empty, is to connect to a Unix-domain
965973
socket<indexterm><primary>Unix domain socket</primary></indexterm> in
966974
<filename>/tmp</filename> (or whatever socket directory was specified
@@ -997,8 +1005,12 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
9971005
<itemizedlist>
9981006
<listitem>
9991007
<para>
1000-
If <literal>host</literal> is specified without <literal>hostaddr</literal>,
1001-
a host name lookup occurs.
1008+
If <literal>host</literal> is specified
1009+
without <literal>hostaddr</literal>, a host name lookup occurs.
1010+
(When using <function>PQconnectPoll</function>, the lookup occurs
1011+
when <function>PQconnectPoll</function> first considers this host
1012+
name, and it may cause <function>PQconnectPoll</function> to block
1013+
for a significant amount of time.)
10021014
</para>
10031015
</listitem>
10041016
<listitem>

0 commit comments

Comments
 (0)