The PQexec
function is adequate
for submitting commands in simple synchronous applications. It
has a couple of major deficiencies however:
PQexec
waits for the command
to be completed. The application may have other work to do
(such as maintaining a user interface), in which case it
won't want to block waiting for the response.
Since control is buried inside PQexec
, it is hard for the frontend to
decide it would like to try to cancel the ongoing command.
(It can be done from a signal handler, but not
otherwise.)
PQexec
can return only one
PGresult structure. If the
submitted command string contains multiple SQL commands, all but the last PGresult are discarded by PQexec
.
Applications that do not like these limitations can instead
use the underlying functions that PQexec
is built from: PQsendQuery
and PQgetResult
.
Older programs that used this functionality as well as
PQputline
and PQputnbytes
could block waiting to send data to
the backend. To address that issue, the function PQsetnonblocking
was added.
Old applications can neglect to use PQsetnonblocking
and get the older potentially
blocking behavior. Newer programs can use PQsetnonblocking
to achieve a completely
nonblocking connection to the backend.
PQsetnonblocking
Sets the
nonblocking status of the connection.
int PQsetnonblocking(PGconn *conn, int arg)
Sets the state of the connection to nonblocking if
arg
is 1, blocking if
arg
is 0. Returns 0 if OK, -1
if error.
In the nonblocking state, calls to PQputline
, PQputnbytes
, PQsendQuery
and PQendcopy
will not block but instead return
an error if they need to be called again.
When a database connection has been set to nonblocking
mode and PQexec
is called, it
will temporarily set the state of the connection to blocking
until the PQexec
completes.
More of libpq is expected
to be made safe for PQsetnonblocking
functionality in the near
future.
PQisnonblocking
Returns the
blocking status of the database connection.
int PQisnonblocking(const PGconn *conn)
Returns 1 if the connection is set to nonblocking mode, 0 if blocking.
PQsendQuery
Submit a command
to the server without waiting for the result(s). 1 is
returned if the command was successfully dispatched, 0 if not
(in which case, use PQerrorMessage
to get more information
about the failure).
int PQsendQuery(PGconn *conn, const char *query);
After successfully calling PQsendQuery
, call PQgetResult
one or more times to obtain the
results. PQsendQuery
may not be
called again (on the same connection) until PQgetResult
has returned NULL, indicating
that the command is done.
PQgetResult
Wait for the
next result from a prior PQsendQuery
, and return it. NULL is
returned when the query is complete and there will be no more
results.
PGresult *PQgetResult(PGconn *conn);
PQgetResult
must be called
repeatedly until it returns NULL, indicating that the command
is done. (If called when no command is active, PQgetResult
will just return NULL at once.)
Each non-NULL result from PQgetResult
should be processed using the
same PGresult accessor functions previously described. Don't
forget to free each result object with PQclear
when done with it. Note that
PQgetResult
will block only if
a query is active and the necessary response data has not yet
been read by PQconsumeInput
.
Using PQsendQuery
and
PQgetResult
solves one of
PQexec
's problems: If a command
string contains multiple SQL
commands, the results of those commands can be obtained
individually. (This allows a simple form of overlapped
processing, by the way: the frontend can be handling the results
of one query while the backend is still working on later queries
in the same command string.) However, calling PQgetResult
will still cause the frontend to
block until the backend completes the next SQL command. This can be avoided by proper
use of three more functions:
PQconsumeInput
If input is
available from the backend, consume it.
int PQconsumeInput(PGconn *conn);
PQconsumeInput
normally
returns 1 indicating "no error",
but returns 0 if there was some kind of trouble (in which
case PQerrorMessage
is set).
Note that the result does not say whether any input data was
actually collected. After calling PQconsumeInput
, the application may check
PQisBusy
and/or PQnotifies
to see if their state has
changed.
PQconsumeInput
may be called
even if the application is not prepared to deal with a result
or notification just yet. The routine will read available
data and save it in a buffer, thereby causing a select()
read-ready indication to go away.
The application can thus use PQconsumeInput
to clear the select()
condition immediately, and then
examine the results at leisure.
PQisBusy
Returns 1 if a
query is busy, that is, PQgetResult
would block waiting for input.
A 0 return indicates that PQgetResult
can be called with assurance of
not blocking.
int PQisBusy(PGconn *conn);
PQisBusy
will not itself
attempt to read data from the backend; therefore PQconsumeInput
must be invoked first, or
the busy state will never end.
PQflush
Attempt to flush any
data queued to the backend, returns 0 if successful (or if
the send queue is empty) or EOF if it
failed for some reason.
int PQflush(PGconn *conn);
PQflush
needs to be called
on a nonblocking connection before calling select()
to determine if a response has
arrived. If 0 is returned it ensures that there is no data
queued to the backend that has not actually been sent. Only
applications that have used PQsetnonblocking
have a need for this.
PQsocket
Obtain the file
descriptor number for the backend connection socket. A valid
descriptor will be >= 0; a result of -1 indicates that no
backend connection is currently open.
int PQsocket(const PGconn *conn);
PQsocket
should be used to
obtain the backend socket descriptor in preparation for
executing select()
. This allows
an application using a blocking connection to wait for either
backend responses or other conditions. If the result of
select()
indicates that data
can be read from the backend socket, then PQconsumeInput
should be called to read the
data; after which, PQisBusy
,
PQgetResult
, and/or
PQnotifies
can be used to
process the response.
Nonblocking connections (that have used PQsetnonblocking
) should not use
select()
until PQflush
has returned 0 indicating that
there is no buffered data waiting to be sent to the
backend.
A typical frontend using these functions will have a main loop
that uses select
to wait for all
the conditions that it must respond to. One of the conditions
will be input available from the backend, which in select
's terms is readable data on the file
descriptor identified by PQsocket
.
When the main loop detects input ready, it should call
PQconsumeInput
to read the input.
It can then call PQisBusy
, followed
by PQgetResult
if PQisBusy
returns false (0). It can also call
PQnotifies
to detect NOTIFY
messages (see Section 1.6).
A frontend that uses PQsendQuery
/PQgetResult
can also attempt to cancel a
command that is still being processed by the backend.
PQrequestCancel
Request that
PostgreSQL abandon
processing of the current command.
int PQrequestCancel(PGconn *conn);
The return value is 1 if the cancel request was
successfully dispatched, 0 if not. (If not, PQerrorMessage
tells why not.) Successful
dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of
PQrequestCancel
, the
application must continue with the normal result-reading
sequence using PQgetResult
. If
the cancellation is effective, the current command will
terminate early and return an error result. If the
cancellation fails (say, because the backend was already done
processing the command), then there will be no visible result
at all.
Note that if the current command is part of a transaction, cancellation will abort the whole transaction.
PQrequestCancel
can safely be
invoked from a signal handler. So, it is also possible to use it
in conjunction with plain PQexec
,
if the decision to cancel can be made in a signal handler. For
example, psql invokes
PQrequestCancel
from a SIGINT signal handler, thus allowing
interactive cancellation of queries that it issues through
PQexec
. Note that PQrequestCancel
will have no effect if the
connection is not currently open or the backend is not currently
processing a command.