Ordinarily, libpq collects a SQL command's
entire result and returns it to the application as a single
PGresult
. This can be unworkable for commands
that return a large number of rows. For such cases, applications can use
PQsendQuery
and PQgetResult
in
single-row mode. In this mode, the result row(s) are
returned to the application one at a time, as they are received from the
server.
To enter single-row mode, call PQsetSingleRowMode
immediately after a successful call of PQsendQuery
(or a sibling function). This mode selection is effective only for the
currently executing query. Then call PQgetResult
repeatedly, until it returns null, as documented in Section 33.4. If the query returns any rows, they are returned
as individual PGresult
objects, which look like
normal query results except for having status code
PGRES_SINGLE_TUPLE
instead of
PGRES_TUPLES_OK
. After the last row, or immediately if
the query returns zero rows, a zero-row object with status
PGRES_TUPLES_OK
is returned; this is the signal that no
more rows will arrive. (But note that it is still necessary to continue
calling PQgetResult
until it returns null.) All of
these PGresult
objects will contain the same row
description data (column names, types, etc) that an ordinary
PGresult
object for the query would have.
Each object should be freed with PQclear
as usual.
PQsetSingleRowMode
Select single-row mode for the currently-executing query.
int PQsetSingleRowMode(PGconn *conn);
This function can only be called immediately after
PQsendQuery
or one of its sibling functions,
before any other operation on the connection such as
PQconsumeInput
or
PQgetResult
. If called at the correct time,
the function activates single-row mode for the current query and
returns 1. Otherwise the mode stays unchanged and the function
returns 0. In any case, the mode reverts to normal after
completion of the current query.
While processing a query, the server may return some rows and then
encounter an error, causing the query to be aborted. Ordinarily,
libpq discards any such rows and reports only the
error. But in single-row mode, those rows will have already been
returned to the application. Hence, the application will see some
PGRES_SINGLE_TUPLE
PGresult
objects followed by a PGRES_FATAL_ERROR
object. For
proper transactional behavior, the application must be designed to
discard or undo whatever has been done with the previously-processed
rows, if the query ultimately fails.