31.5. 逐行检索查询结果 #
通常，libpq 会收集一条 SQL 命令的完整结果，并将其作为单个 PGresult 返回给应用程序。对于返回大量行的命令，这种方式可能不可行。在这种情况下，应用程序可以在单行模式下使用 PQsendQuery 和 PQgetResult。此模式在从服务器收到结果行时，每次将一行返回给应用程序。
要进入单行模式，请在成功调用 PQsendQuery（或其同类函数）后，立即调用 PQsetSingleRowMode。此模式选择仅对当前正在执行的查询生效。然后按照第 31.4 节所述，反复调用 PQgetResult，直到返回空指针。如果查询返回了行，每一行都作为独立的 PGresult 对象返回。这些对象看起来与普通查询结果相同，只是状态码为 PGRES_SINGLE_TUPLE，而不是 PGRES_TUPLES_OK。最后一行之后，或者查询返回零行时立即返回一个不含行、状态为 PGRES_TUPLES_OK 的对象，表示不会再有更多行到达。（但注意，仍然必须继续调用 PQgetResult，直到返回空指针。）所有这些 PGresult 对象都包含与该查询普通 PGresult 对象相同的行描述数据（列名、类型等）。每个对象都应像往常一样使用 PQclear 释放。
PQsetSingleRowMode#为当前正在执行的查询选择单行模式。
int PQsetSingleRowMode(PGconn *conn);
此函数只能在调用
PQsendQuery或其某个同类函数后立即调用，并且必须在对该连接执行任何其他操作之前，例如PQconsumeInput或PQgetResult。在正确时机调用时，此函数会为当前查询启用单行模式并返回 1；否则，模式保持不变，函数返回 0。无论哪种情况，当前查询完成后都会恢复普通模式。
小心
处理查询时，服务器可能先返回一些行，然后遇到错误，导致查询中止。通常，libpq 会丢弃这些行，只报告错误。但在单行模式下，这些行已经返回给了应用程序。因此，应用程序会先看到一些 PGRES_SINGLE_TUPLE PGresult 对象，随后看到一个 PGRES_FATAL_ERROR 对象。为了保证正确的事务行为，如果查询最终失败，应用程序必须能够丢弃或撤销此前对这些行所做的全部操作。