Re: BUG #5837: PQstatus() fails to report lost connection

> -----Original Message-----
> From: Robert Haas [mailto:robertmhaas(at)gmail(dot)com]
> Sent: Tuesday, January 25, 2011 7:33 AM
> To: Kevin Grittner
> Cc: Murray S. Kucherawy; Tom Lane; pgsql-bugs(at)postgresql(dot)org
> Subject: Re: [BUGS] BUG #5837: PQstatus() fails to report lost connection
>
> I think the real, underlying problem here is that Murray would like a
> behavior change: when a FATAL or PANIC condition is reported by the
> server, he'd like the client to immediately close the socket and set
> its status to CONNECTION_BAD. If we're going to clarify the
> documentation, I think that the lack of that behavior is what we
> should try to clarify. For example, it would be good to mention that
> a PGRES_FATAL_ERROR is might corresponding to the server levels ERROR,
> FATAL, or PANIC, and that only in the latter two cases is the
> connection presumably of no further use; and we could also mention
> that libpq doesn't understand anything about the meanings of those
> error levels, so that PQstatus() won't automatically barf just because
> the server has sent a FATAL, *unless* it's read far enough in the
> input stream to detect the problem.

First and foremost, I think a behavior change would be the right thing to do. I can't think of any API that follows this odd model; to me it's like saying select() has reported a socket that's both read-ready and in an exception state, but we won't actually set errno until you iterate on read() until EOF first. Counter-intuitive behaviors in APIs lead to application problems or even user attrition in extreme cases.

That said, I've maintained complex APIs before (in fact, this is all the result of one of them) and I understand what this sort of a change might entail. Thus, the next-best option is to document the idiosyncrasy that's been uncovered; i.e., make the proposed change to the documentation with perhaps an added hint as to why it's necessary. You might want to demonstrate why after one iteration PGgetResult() and PQstatus() seem to indicate no problem while PGresultStatus() and PGresultErrorString() both already seem to know the severity and even the nature of the error.

I think Kevin summed it up nicely. Quite simply, the documentation doesn't match the behavior in this case. One or the other should be adjusted so they are in alignment, while disrupting both your installed base and user experience as little as possible.

-MSK