通常,libpq会收集一个 SQL 命令的整个结果并且把它作为单个PGresult
返回给应用。这对于返回大量行的命令是行不通的。对于这类情况,应用可以使用PQsendQuery
和PQgetResult
的单行模式。在这种模式中,结果行以一次一行的方式被返回给应用。
要进入到单行模式,在一次成功的PQsendQuery
(或者其他兄弟函数)调用后立即调用PQsetSingleRowMode
。这种模式选择只对当前正在执行的查询有效。然后反复调用PQgetResult
,直到它返回空,如第 33.4 节中所示。如果该查询返回行,它们会作为单个的PGresult
对象返回,它们看起来都像普通的查询结果,只不过其状态代码是PGRES_SINGLE_TUPLE
而非PGRES_TUPLES_OK
。在最后一行之后或者紧接着该查询返回零行之后,一个状态为PGRES_TUPLES_OK
的零行对象会被返回,这就是代表不会有更多行的信号(但是注意仍然有必要继续调用PQgetResult
直到它返回空)。所有这些PGresult
对象将包含相同的行描述数据(列名、类型等等),这些数据和通常一个查询的PGresult
对象的相同。每一个对象都应该按常规用PQclear
释放。
在处理一个查询时,服务器可能返回一些行并且接着遇到一个错误导致查询被中断。通常,libpq会丢弃掉这样的行并且至报告错误。但是在单行模式中,那些行(错误之前返回的行)已经被返回给应用。因此,应用将看到一些PGRES_SINGLE_TUPLE
PGresult
对象并且然后看到一个PGRES_FATAL_ERROR
对象。为了得到正确的事务行为,如果查询最终失败,应用必须被设计为丢弃或者撤销使用之前处理的行完成的事情。