Ordinarily, libpq collects a
SQL command's entire result and returns it to the application as a
PGresult. This can be
unworkable for commands that return a large number of rows. For
such cases, applications can use
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
To enter single-row mode, call
PQsetSingleRowMode immediately after a successful
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
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
PGresult object for the
query would have. Each object should be freed with
PQclear as usual.
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
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
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.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.