linkend="libpq-pipeline-errors"/>.

<synopsis>
int PQsendPipelineSync(PGconn *conn);
</synopsis>
      </para>
      <para>
       Returns 1 for success. Returns 0 if the connection is not in
       pipeline mode or sending a
       <link linkend="protocol-flow-ext-query">sync message</link>
       failed.
       Note that the message is not itself flushed to the server automatically;
       use <function>PQflush</function> if necessary.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQsendFlushRequest">
     <term><function>PQsendFlushRequest</function><indexterm><primary>PQsendFlushRequest</primary></indexterm></term>

     <listitem>
      <para>
       Sends a request for the server to flush its output buffer.
<synopsis>
int PQsendFlushRequest(PGconn *conn);
</synopsis>
      </para>

      <para>
       Returns 1 for success.  Returns 0 on any failure.
      </para>
      <para>
       The server flushes its output buffer automatically as a result of
       <function>PQpipelineSync</function> being called, or
       on any request when not in pipeline mode; this function is useful
       to cause the server to flush its output buffer in pipeline mode
       without establishing a synchronization point.
       Note that the request is not itself flushed to the server automatically;
       use <function>PQflush</function> if necessary.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="libpq-pipeline-tips">
   <title>When to Use Pipeline Mode</title>

   <para>
    Much like asynchronous query mode, there is no meaningful performance
    overhead when using pipeline mode. It increases client application complexity,
    and extra caution is required to prevent client/server deadlocks, but
    pipeline mode can offer considerable performance improvements, in exchange for
    increased memory usage from leaving state around longer.
   </para>

   <para>
    Pipeline mode is most useful when the server is distant, i.e., network latency
    (<quote>ping time</quote>) is high, and also when many small operations
    are being performed in rapid succession.  There is usually less benefit
    in using pipelined commands when each query takes many multiples of the client/server
    round-trip time to execute.  A 100-statement operation run on a server
    300 ms round-trip-time away would take 30 seconds in network latency alone
    without pipelining; with pipelining it may spend as little as 0.3 s waiting for
    results from the server.
   </para>

   <para>
    Use pipelined commands when your application does lots of small
    <literal>INSERT</literal>, <literal>UPDATE</literal> and
    <literal>DELETE</literal> operations that can't easily be transformed
    into operations on sets, or into a <literal>COPY</literal> operation.
   </para>

   <para>
    Pipeline mode is not useful when information from one operation is required by
    the client to produce the next operation. In such cases, the client
    would have to introduce a synchronization point and wait for a full client/server
    round-trip to get the results it needs. However, it's often possible to
    adjust the client design to exchange the required information server-side.
    Read-modify-write cycles are especially good candidates; for example:
<programlisting>
BEGIN;
SELECT x FROM mytable WHERE id = 42 FOR UPDATE;
-- result: x=2
-- client adds 1 to x:
UPDATE mytable SET x = 3 WHERE id = 42;
COMMIT;
</programlisting>
    could be much more efficiently done with:
<programlisting>
UPDATE mytable SET x = x + 1 WHERE id = 42;
</programlisting>
   </para>

   <para>
    Pipelining is less useful, and more complex, when a single pipeline contains
    multiple transactions (see <xref linkend="libpq-pipeline-errors"/>).
   </para>
  </sect2>
 </sect1>

 <!-- keep this not-too-apropos sect1 ID for stability of doc URLs -->
 <sect1 id="libpq-single-row-mode">
  <title>Retrieving Query Results in