通常,libpq 会收集一条 SQL 命令的完整结果,并将其作为单个 PGresult 返回给应用程序。对于返回大量行的命令,这种方式可能不可行。在这种情况下,应用程序可以在单行模式下使用 PQsendQuery 和 PQgetResult。此模式在从服务器收到结果行时,每次将一行返回给应用程序。
要进入单行模式,请在成功调用 PQsendQuery(或其同类函数)后,立即调用 PQsetSingleRowMode。此模式选择仅对当前正在执行的查询生效。然后按照 Section 33.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 对象。为了保证正确的事务行为,如果查询最终失败,应用程序必须能够丢弃或撤销此前对这些行所做的全部操作。