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>
Openpgp: preference=signencrypt
Autocrypt: addr=mail@joeconway.com; keydata=
 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
Message-ID: <354b3a34-29b8-842d-bf00-42612464342e@joeconway.com>
Date: Tue, 25 Sep 2018 15:58:12 -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: <1f9d1514-f087-1b11-9b45-aac91e57bdc2@joeconway.com>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="o2GobZyVNdqWpkygFNQPRyWedJ7dAjgD5"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--o2GobZyVNdqWpkygFNQPRyWedJ7dAjgD5
Content-Type: multipart/mixed; boundary="9jUpfB6nOl8Jws3Vy85uNYiMwWiSv9ViU";
 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: <354b3a34-29b8-842d-bf00-42612464342e@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>
In-Reply-To: <1f9d1514-f087-1b11-9b45-aac91e57bdc2@joeconway.com>

--9jUpfB6nOl8Jws3Vy85uNYiMwWiSv9ViU
Content-Type: multipart/mixed;
 boundary="------------CA0E39668BEC0B88C7082A8D"
Content-Language: en-US

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

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 e=
rror 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 be=

> back-patched.
>=20
>=20
>>> Secondly
>>> dblink_is_busy must be first called to make dblink_error_message retu=
rns 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 thin=
k 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 unti=
l
> 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 asynchronous=

> query() will be visible.
> ------------

And now with the corresponding patch attached.

Thoughts/comments?

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

--------------CA0E39668BEC0B88C7082A8D
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

--------------CA0E39668BEC0B88C7082A8D--

--9jUpfB6nOl8Jws3Vy85uNYiMwWiSv9ViU--

--o2GobZyVNdqWpkygFNQPRyWedJ7dAjgD5
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

iQIcBAEBCAAGBQJbqpNUAAoJEDfy90M199hlgNQP/1VyNW7Z6OupsNSzu1EATu39
YtvmJl2M5+oEIT4TF+ktMkb+8Md9XADS8PYAMUeS0p5R0+ARwJ42G9qy+16yRegb
EOMRWH9NmAYD8eD9uqxnT9k6KRGWiMULmJ/7hiQ8mNg+nuODsjoWhV+6L5YGnNwa
mCLCrUqEWTqm4iL+XEsFvsH1MH7HOOqPzq1zll8wO7zCzCZ6c/WXMSzvAi6fS0nb
4Rybc3F5bgmxFlwnjxW9D1HaC3oLB6xDNzLtkvA+WUZ4a6zHZo+9wpYKRwg9Zpwr
ikQRhZOh/qV1DAcWPmWff1DshgnY+nDtW+N0k4E/e25a8pWMM9dUWvnzp9aUV4pR
yLLGBylGab7Fl875HlmH0v3GkIGo1S95qNj+QLNG7whlV8He2fPuA4AEejYQeep6
OanG/rlltz5vdj3GeeqLKZJcbKJAxTpB6sWi066x5NvIRU6kHcFIkvskj7wOkuQp
NNhX0GHmIPucfb7RGCo/hVC2Eu5jJ5MXsbLh7RixUyQJmJZ0XJht8kvGJm1yEjRw
1MxJu0HD6uiKr0VnEsD5ud27Q8DbWecxUhWtfNTCDT40XPnPfnBvV5j5w+9fFuC5
SI/begYnuNWZuoUXSFZqsEGO3cr07NawSn4m10+pHIv93C/HImZK79Ccxy9V/DjK
TyZgLObtrFVPHuV0ku0P
=DvUK
-----END PGP SIGNATURE-----

--o2GobZyVNdqWpkygFNQPRyWedJ7dAjgD5--