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
>From 4ba9bca8a7cf6b72a9fae6b4ee8abb54d9ad8d8a Mon Sep 17 00:00:00 2001
From: Craig Ringer <cr...@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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
