Message-ID: <53ABE01D.7070206@2ndquadrant.com>
Date: Thu, 26 Jun 2014 16:55:57 +0800
From: Craig Ringer <craig@2ndquadrant.com>
Organization: 2nd Quadrant
User-Agent: Mozilla/5.0 (X11; Linux x86_64;
 rv:24.0) Gecko/20100101 Thunderbird/24.4.0
MIME-Version: 1.0
To: PostgreSQL Developers <pgsql-docs@postgresql.org>
Subject: PQping docs note
Content-Type: multipart/mixed; boundary="------------080707040902000604000306"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

This is a multi-part message in MIME format.
--------------080707040902000604000306
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

Hi all

Here's a small docs change telling users that PQping isn't for
connection testing - it makes a new connection. Also warn users that
connection "testing" is futile and they should just handle errors.

This came out of user feedback on the libpq docs by a new user.

Should apply cleanly to master with "git am".

-- 
 Craig Ringer                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

--------------080707040902000604000306
Content-Type: text/x-patch;
 name="0001-PQping-pings-the-server-not-a-connection.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="0001-PQping-pings-the-server-not-a-connection.patch"

From 4ba9bca8a7cf6b72a9fae6b4ee8abb54d9ad8d8a Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig@2ndquadrant.com>
Date: Thu, 26 Jun 2014 16:53:02 +0800
Subject: [PATCH] PQping pings the server, not a connection

Add a note to the docs telling people that you can't use PQping to test a
connection, and you shouldn't test connections anyway.

Added after user feedback on the docs indicated confusion about the purpose of
PQping.
---
 doc/src/sgml/libpq.sgml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index e10ccec..f7baf6c 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -660,6 +660,18 @@ PGPing PQpingParams(const char * const *keywords,
                     int expand_dbname);
 </synopsis>
 
+      </para>
+      <note>
+       <para>
+		PQping is not for testing whether an existing connection is still
+		usable. It makes a new temporary connection to test if the server is
+		reachable. Instead of testing connections (which is inherently prone to
+		race conditions), just run your queries and retry the transaction if
+		the connection drops.
+	   </para>
+      </note>
+
+      <para>
        The function returns one of the following values:
 
        <variablelist>
-- 
1.9.0


--------------080707040902000604000306
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--------------080707040902000604000306--