PGresult. This can be unworkable for commands that return a large number of rows. For such cases, applications can use
PQgetResultin 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.
PQsetSingleRowModeimmediately after a successful call of
PQsendQuery(or a sibling function). This mode selection is effective only for the currently executing query. Then call
PQgetResultrepeatedly, until it returns null, as documented in Section 33.4. If the query returns any rows, they are returned as individual
PGresultobjects, which look like normal query results except for having status code
PGRES_TUPLES_OK. After the last row, or immediately if the query returns zero rows, a zero-row object with status
PGRES_TUPLES_OKis returned; this is the signal that no more rows will arrive. (But note that it is still necessary to continue calling
PQgetResultuntil it returns null.) All of these
PGresultobjects will contain the same row description data (column names, types, etc) that an ordinary
PGresultobject for the query would have. Each object should be freed with
PQsendQueryor 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.
PGresultobjects followed by a
PGRES_FATAL_ERRORobject. 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.