# 34.6. Retrieving Query Results Row-by-Row

Ordinarily, libpq collects an SQL command's entire result and returns it to the application as a singlePGresult. This can be unworkable for commands that return a large number of rows. For such cases, applications can usePQsendQueryandPQgetResultinsingle-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, callPQsetSingleRowModeimmediately after a successful call ofPQsendQuery(or a sibling function). This mode selection is effective only for the currently executing query. Then callPQgetResultrepeatedly, until it returns null, as documented inSection 34.4. If the query returns any rows, they are returned as individualPGresultobjects, which look like normal query results except for having status codePGRES_SINGLE_TUPLEinstead ofPGRES_TUPLES_OK. After the last row, or immediately if the query returns zero rows, a zero-row object with statusPGRES_TUPLES_OKis returned; this is the signal that no more rows will arrive. (But note that it is still necessary to continue callingPQgetResultuntil it returns null.) All of thesePGresultobjects will contain the same row description data (column names, types, etc) that an ordinaryPGresultobject for the query would have. Each object should be freed withPQclearas usual.

When using pipeline mode, single-row mode needs to be activated for each query in the pipeline before retrieving results for that query withPQgetResult. SeeSection 34.5for more information.

PQsetSingleRowMode

Select single-row mode for the currently-executing query.

int PQsetSingleRowMode(PGconn *conn);

This function can only be called immediately afterPQsendQueryor one of its sibling functions, before any other operation on the connection such asPQconsumeInputorPQgetResult. 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.

# Caution

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 somePGRES_SINGLE_TUPLE PGresultobjects followed by aPGRES_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.