codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.6. Retrieving Query Results Row-by-Row</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode" /><link rel="next" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.6. Retrieving Query Results Row-by-Row</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-SINGLE-ROW-MODE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.6. Retrieving Query Results Row-by-Row <a href="#LIBPQ-SINGLE-ROW-MODE" class="id_link">#</a></h2></div></div></div><a id="id-1.7.3.13.2" class="indexterm"></a><p>3   Ordinarily, <span class="application">libpq</span> collects an SQL command's4   entire result and returns it to the application as a single5   <code class="structname">PGresult</code>.  This can be unworkable for commands6   that return a large number of rows.  For such cases, applications can use7   <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> in8   <em class="firstterm">single-row mode</em>.  In this mode, the result row(s) are9   returned to the application one at a time, as they are received from the10   server.11  </p><p>12   To enter single-row mode, call <a class="xref" href="libpq-single-row-mode.html#LIBPQ-PQSETSINGLEROWMODE"><code class="function">PQsetSingleRowMode</code></a>13   immediately after a successful call of <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>14   (or a sibling function).  This mode selection is effective only for the15   currently executing query.  Then call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>16   repeatedly, until it returns null, as documented in <a class="xref" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Section 34.4</a>.  If the query returns any rows, they are returned17   as individual <code class="structname">PGresult</code> objects, which look like18   normal query results except for having status code19   <code class="literal">PGRES_SINGLE_TUPLE</code> instead of20   <code class="literal">PGRES_TUPLES_OK</code>.  After the last row, or immediately if21   the query returns zero rows, a zero-row object with status22   <code class="literal">PGRES_TUPLES_OK</code> is returned; this is the signal that no23   more rows will arrive.  (But note that it is still necessary to continue24   calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> until it returns null.)  All of25   these <code class="structname">PGresult</code> objects will contain the same row26   description data (column names, types, etc.) that an ordinary27   <code class="structname">PGresult</code> object for the query would have.28   Each object should be freed with <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> as usual.29  </p><p>30   When using pipeline mode, single-row mode needs to be activated for each31   query in the pipeline before retrieving results for that query32   with <code class="function">PQgetResult</code>.33   See <a class="xref" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Section 34.5</a> for more information.34  </p><p>35   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETSINGLEROWMODE"><span class="term"><code class="function">PQsetSingleRowMode</code><a id="id-1.7.3.13.6.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSINGLEROWMODE" class="id_link">#</a></dt><dd><p>36       Select single-row mode for the currently-executing query.37 38</p><pre class="synopsis">39int PQsetSingleRowMode(PGconn *conn);40</pre><p>41      </p><p>42       This function can only be called immediately after43       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> or one of its sibling functions,44       before any other operation on the connection such as45       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>46     </a> or47       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.  If called at the correct time,48       the function activates single-row mode for the current query and49       returns 1.  Otherwise the mode stays unchanged and the function50       returns 0.  In any case, the mode reverts to normal after51       completion of the current query.52      </p></dd></dl></div><p>53  </p><div class="caution"><h3 class="title">Caution</h3><p>54    While processing a query, the server may return some rows and then55    encounter an error, causing the query to be aborted.  Ordinarily,56    <span class="application">libpq</span> discards any such rows and reports only the57    error.  But in single-row mode, those rows will have already been58    returned to the application.  Hence, the application will see some59    <code class="literal">PGRES_SINGLE_TUPLE</code> <code class="structname">PGresult</code>60    objects followed by a <code class="literal">PGRES_FATAL_ERROR</code> object.  For61    proper transactional behavior, the application must be designed to62    discard or undo whatever has been done with the previously-processed63    rows, if the query ultimately fails.64   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.5. Pipeline Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.7. Canceling Queries in Progress</td></tr></table></div></body></html>