Subject: Re: dblink_error_message return value
From: Joe Conway <mail@joeconway.com>
To: Tom Lane <tgl@sss.pgh.pa.us>, realyota@gmail.com
Cc: pgsql-docs@lists.postgresql.org
References: <153371978486.1298.2091761143788088262@wrigleys.postgresql.org>
 <28231.1533743837@sss.pgh.pa.us>
 <1f9d1514-f087-1b11-9b45-aac91e57bdc2@joeconway.com>
 <354b3a34-29b8-842d-bf00-42612464342e@joeconway.com>
Openpgp: preference=signencrypt
Autocrypt: addr=mail@joeconway.com; keydata=
 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
Message-ID: <e8571c4e-5dd2-4224-e6a7-f6b774e28b1f@joeconway.com>
Date: Tue, 2 Oct 2018 08:45:37 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.9.1
MIME-Version: 1.0
In-Reply-To: <354b3a34-29b8-842d-bf00-42612464342e@joeconway.com>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="bEQYGKJcF93rNqHZTdcy8W0Txhs3KCAMj"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--bEQYGKJcF93rNqHZTdcy8W0Txhs3KCAMj
Content-Type: multipart/mixed; boundary="mTPutCTW8O63cnLtmsDISAZDyZyvPQomg";
 protected-headers="v1"
From: Joe Conway <mail@joeconway.com>
To: Tom Lane <tgl@sss.pgh.pa.us>, realyota@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Message-ID: <e8571c4e-5dd2-4224-e6a7-f6b774e28b1f@joeconway.com>
Subject: Re: dblink_error_message return value
References: <153371978486.1298.2091761143788088262@wrigleys.postgresql.org>
 <28231.1533743837@sss.pgh.pa.us>
 <1f9d1514-f087-1b11-9b45-aac91e57bdc2@joeconway.com>
 <354b3a34-29b8-842d-bf00-42612464342e@joeconway.com>
In-Reply-To: <354b3a34-29b8-842d-bf00-42612464342e@joeconway.com>

--mTPutCTW8O63cnLtmsDISAZDyZyvPQomg
Content-Type: multipart/mixed;
 boundary="------------FCD292632092ACFA6D6AB0D7"
Content-Language: en-US

This is a multi-part message in MIME format.
--------------FCD292632092ACFA6D6AB0D7
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

On 09/25/2018 03:58 PM, Joe Conway wrote:
> On 09/25/2018 01:50 PM, Joe Conway wrote:
>> On 08/08/2018 11:57 AM, Tom Lane wrote:
>>> =3D?utf-8?q?PG_Doc_comments_form?=3D <noreply@postgresql.org> writes:=

>>>> The following documentation comment has been logged on the website:
>>>> Documentation says:
>>>=20
>>>> Return Value
>>>> Returns last error message, or an empty string if there has been no =
error in
>>>> this connection.
>>>> Which is invalid.
>>>> Actually it returns 'OK' string if no error was raised.
>>>=20
>>> Good catch!  The code's quite clear about it, but the SGML docs need
>>> fixed.
>>=20
>>=20
>> As mentioned on the nearby thread, will fix. I suppose this ought to b=
e
>> back-patched.
>>=20
>>=20
>>>> Secondly
>>>> dblink_is_busy must be first called to make dblink_error_message ret=
urns an
>>>> error message. (Tested on 9.6.9)
>>>=20
>>> Meh.  I see what you're getting at here, I think, but that seems like=
 a
>>> completely wrong/misleading statement of the issue.  Joe, can you thi=
nk of
>>> better phraseology?
>>=20
>> Maybe a note, something like this?
>> ------------
>> When asynchronous queries are initiated by dblink_send_query(), the
>> error message associated with the connection might not get updated unt=
il
>> the server's response message is consumed. This typically means that
>> dblink_is_busy() or dblink_get_result() should be called prior to
>> dblink_error_message(), so that any error generated by the asynchronou=
s
>> query() will be visible.
>> ------------
>=20
> And now with the corresponding patch attached.
>=20
> Thoughts/comments?


Going once, going twice, ...
(if no complaints will commit soon)

Joe

--=20
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development

--------------FCD292632092ACFA6D6AB0D7
Content-Type: text/x-patch;
 name="doc-dblink_error_message-01.patch"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
 filename="doc-dblink_error_message-01.patch"

diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 87e14ea..97dc3b8 100644
*** a/doc/src/sgml/dblink.sgml
--- b/doc/src/sgml/dblink.sgml
*************** dblink_error_message(text connname) retu
*** 1165,1175 ****
     <title>Return Value</title>
 =20
     <para>
!     Returns last error message, or an empty string if there has been
      no error in this connection.
     </para>
    </refsect1>
 =20
    <refsect1>
     <title>Examples</title>
 =20
--- 1165,1189 ----
     <title>Return Value</title>
 =20
     <para>
!     Returns last error message, or <literal>OK</literal> if there has b=
een
      no error in this connection.
     </para>
    </refsect1>
 =20
+   <refsect1>
+    <title>Notes</title>
+=20
+    <para>
+     When asynchronous queries are initiated by
+     <function>dblink_send_query</function>, the error message associate=
d with
+     the connection might not get updated until the server's response me=
ssage
+     is consumed. This typically means that <function>dblink_is_busy</fu=
nction>
+     or <function>dblink_get_result</function> should be called prior to=

+     <function>dblink_error_message</function>, so that any error genera=
ted by
+     the asynchronous query will be visible.
+    </para>
+   </refsect1>
+=20
    <refsect1>
     <title>Examples</title>
 =20

--------------FCD292632092ACFA6D6AB0D7--

--mTPutCTW8O63cnLtmsDISAZDyZyvPQomg--

--bEQYGKJcF93rNqHZTdcy8W0Txhs3KCAMj
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJbs2hxAAoJEDfy90M199hlH/EP/jWgVSaO8SIwmB30NPL+ajdl
EDSjLz88OzmGqBZlu6aQaBpW+YjNn1kdcpggCvfaqK4hgxkY6pS4sPCoV4l6J1u3
mnvPV0x+dHNkkb/uGkNh5axlkg5vHaTzDJJUDfGnpur7X7/op9wna8JeBqMGA7y1
AP9ISV6xzwRP5C8w70zckboriZgDN9ZZSYigu2IPDQmIU8xVXxjE7nMxa7UrE3j9
koFuaCGDcAAIu7nP5pCHONLELGVCeU7+A6fsyyRkvq7IxVBOncLDoLCy+7CWEoNb
Py2Qk86Ro24UMyKkYbrJqQ0zRy0W5eIsivyIAK0IvKcX0w0sIfHVHeAqt9ewFug1
eu0VApLpE9z/QhZu9GRXs1yj7ma5FWwpl1GtJH/dId1NkToLZnSGK6V6nEkIVLLq
zPJthAcwCKRk/nNvo7MsDb70AlaI42DFvOmP4XOLHYoYY5utalifZ5ssWF+PanAX
iZDidLdtmiimQWCGGRje6HjGEe7zuZ+qWqReimP0cjjh5rsSl1cVLWSmzxDrXkeX
0vHP/9yL/ZqHPr00q150ztHKF4dSq63QZuR3/ED8fTzJnuA/pc2qnR2Q/PhxYWel
XM+KLTcbOyPJZgZ3A3xVw+wxEThYbEogWf83vXdLm+HXXV852i11qp71hundyhl8
RTF/K8zjLPy2mBfeQHQe
=FwPV
-----END PGP SIGNATURE-----

--bEQYGKJcF93rNqHZTdcy8W0Txhs3KCAMj--