33.5. 按行检索查询结果

通常,libpq 收集 SQL 命令的整个结果,并将其作为单个PGresult返回给应用程序。对于返回大量行的命令,这可能不可行。在这种情况下,应用程序可以在单行模式中使用PQsendQueryPQgetResult。在这种模式下,结果行是从服务器接收到的,每次一次返回给应用程序。

要进入单行模式,请成功调用PQsendQuery(或同级函数)后立即调用PQsetSingleRowMode。此模式选择仅对当前正在执行的查询有效。然后重复调用PQgetResult,直到返回_,如Section 33.4中所述。如果查询返回任何行,它们将作为单独的PGresult对象返回,除了具有状态代码PGRES_SINGLE_TUPLE而不是PGRES_TUPLES_OK之外,它们看起来像普通的查询结果。在最后一行之后,或者如果查询返回零行,则立即返回状态为PGRES_TUPLES_OK的零行对象;这表明不再有行到达。 (但请注意,仍然需要 continue 调用PQgetResult,直到它返回 null.)所有这些PGresult对象将包含与查询的普通PGresult对象相同的行描述数据(列名,类型等)。通常,每个对象都应使用PQclear释放。

  • PQsetSingleRowMode
    • 为当前正在执行的查询选择单行模式。
int PQsetSingleRowMode(PGconn *conn);

该函数只能在PQsendQuery或其同级函数之一之后,在对连接PQconsumeInputPQgetResult进行的任何其他操作之前立即调用。如果在正确的时间调用,该函数将激活当前查询的单行模式并返回 1.否则,该模式保持不变,并且函数返回 0.无论如何,该模式将在当前查询完成后恢复为正常。

Caution

在处理查询时,服务器可能会返回一些行,然后遇到错误,从而导致查询中止。通常,libpq 会丢弃所有此类行并仅报告错误。但是在单行模式下,这些行将已经返回给应用程序。因此,应用程序将看到一些PGRES_SINGLE_TUPLE PGresult对象,然后是PGRES_FATAL_ERROR对象。为了实现正确的事务行为,如果查询最终失败,则必须将应用程序设计为丢弃或撤消对先前处理的行所做的任何操作。