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

> -----Original Message-----
> From: Kevin Grittner [mailto:Kevin(dot)Grittner(at)wicourts(dot)gov]
> Sent: Monday, January 24, 2011 9:50 AM
> To: Murray S. Kucherawy; Tom Lane
> Cc: Robert Haas; pgsql-bugs(at)postgresql(dot)org
> Subject: Re: [BUGS] BUG #5837: PQstatus() fails to report lost connection
>
> "Murray S. Kucherawy" <msk(at)cloudmark(dot)com> wrote:
>
> > Please, at a minimum, add some documentation about it.
>
> Current documentation at:
>
> http://www.postgresql.org/docs/9.0/interactive/libpq-async.html
>
> says:
>
> | PQgetResult must be called repeatedly until it returns a null
> | pointer, indicating that the command is done.
>
> What do you think would make this more clear?

"command is done" sounds like normal operation to me, but we're talking about an obvious exception here. The command (I assume that means the query that ultimately failed) can't even have started because the connection was gone. That's why I find the description misleading.

Indeed, the function order you're talking about is PQgetResult(), which returns non-NULL in this condition (which looks like there's a result available), but then PQresultStatus() returns PGRES_FATAL_ERROR. It's not very obvious to me that the right thing to do here is call PQgetResult() again just to get PQstatus() to tell me the truth. Now we're dealing with an exception rather than something normal.

So maybe something like this after the paragraph you cited would help:

"Note that after returning a PGresult object, PQresultStatus() could indicate a fatal error. The caller should still iterate calling PQgetResult() to completion (i.e. until it returns NULL) in order to allow libpq to process the error information completely."