Fix documentation for dblink_error_message() return value

The dblink documentation claims that an empty string is returned if there
has been no error, however OK is actually returned in that case. Also,
clarify that an async error may not be seen unless dblink_is_busy() or
dblink_get_result() have been called first.

Backpatch to all supported branches.

Reported-by: realyota
Backpatch-through: 9.4
Discussion: https://postgr.es/m/153371978486.1298.2091761143788088262@wrigleys.postgresql.org

diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 87e14ea093def7e481f79ec52e30d8b98616340f..97dc3b81292871963c83855ee1930343812bba7a 100644 (file)
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -1165,11 +1165,25 @@ dblink_error_message(text connname) returns text
    Return Value
 
    
-    Returns last error message, or an empty string if there has been
+    Returns last error message, or OK if there has been
     no error in this connection.
    
   
 
+  
+   Notes
+
+   
+    When asynchronous queries are initiated by
+    dblink_send_query, the error message associated with
+    the connection might not get updated until 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.
+   
+  
+
   
    Examples