public inbox for [email protected]
help / color / mirror / Atom feedFrom: Craig Ringer <[email protected]>
To: PostgreSQL Developers <[email protected]>
Subject: PQping docs note
Date: Thu, 26 Jun 2014 16:55:57 +0800
Message-ID: <[email protected]> (raw)
List-Unsubscribe: <mailto:[email protected]?body=unsub%20pgsql-docs>
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
--
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
[text/x-patch] 0001-PQping-pings-the-server-not-a-connection.patch (1.3K, 2-0001-PQping-pings-the-server-not-a-connection.patch)
download | inline diff:
From 4ba9bca8a7cf6b72a9fae6b4ee8abb54d9ad8d8a Mon Sep 17 00:00:00 2001
From: Craig Ringer <[email protected]>
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
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected]
Subject: Re: PQping docs note
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox