Построчное извлечение результатов запроса

Обычно libpq собирает весь результат SQL и возвращает его приложению в виде единственного объекта PGresult. Это может быть неосуществимо для команд, возвращающих огромное количество строк. В таких случаях приложение может использовать функции PQsendQuery и PQgetResult в однострочном режиме. В этом режиме результирующие строки возвращаются приложению по одной за раз, по мере их получения от сервера.

Для входа в однострочный режим вызовите функцию PQsetSingleRowMode сразу после успешного вызова PQsendQuery (или родственной ей функции). Выбор этого режима действителен только для запроса, обрабатываемого в настоящий момент. Затем повторно вызывайте PQgetResult, пока та не вернет NULL, как описано в разделе Асинхронная обработка команд. Если запрос возвращает некоторое количество строк, они возвращаются в виде отдельных объектов PGresult, которые выглядят как обычные результаты запроса, но имеют код статуса PGRES_SINGLE_TUPLE вместо PGRES_TUPLES_OK. После последней строки или сразу, если запрос не возвращает ни одной строки, возвращается объект, не содержащий строк, со статусом PGRES_TUPLES_OK; это сигнал о том, что больше строки поступать не будут. (Но обратите внимание, что все равно нужно продолжать вызывать PQgetResult, пока та не вернет NULL.) Все эти объекты PGresult будут содержать те же самые данные, описывающие строки (имена столбцов, типы и т. д.), которые имел бы обычный объект PGresult для этого запроса. Память, занимаемую каждым объектом, следует освобождать с помощью функции PQclear, как обычно.

При использовании конвейерного режима однострочный режим нужно активировать для каждого запроса в конвейере, прежде чем получать результаты для этого запроса с помощью функции PQgetResult. Подробную информацию см. в разделе Конвейерный режим.

PQsetSingleRowMode

Выбрать однострочный режим для запроса, выполняющегося в настоящий момент.

int PQsetSingleRowMode(PGconn *conn);

Эту функцию можно вызвать только сразу после PQsendQuery или одной из родственных ей функций, до выполнения всех остальных операций через это соединение, например PQconsumeInput или PQgetResult. При вызове в подходящий момент эта функция активирует однострочный режим для текущего запроса и возвращает 1. В противном случае режим остается прежним, а функция возвращает 0. В любом случае после завершения текущего запроса режим сбрасывается до обычного.

ВНИМАНИЕ!
Во время обработки запроса сервер может возвратить несколько строк, а затем столкнуться с ошибкой, из-за чего запрос прерывается. Обычно libpq отбрасывает такие строки и сообщает только об ошибке. Но в однострочном режиме эти строчки уже будут возвращены приложению. Как следствие, приложение увидит несколько объектов PGresult со статусом PGRES_SINGLE_TUPLE, а следом за ними — объект со статусом PGRES_FATAL_ERROR. Для обеспечения надлежащего поведения транзакций приложение должно быть разработано так, чтобы отбрасывать или отменять все операции, проведенные с ранее обработанными строками, если запрос в итоге завершается сбоем.