write-ready, call
   <xref linkend="libpq-PQflush"/> again.  If it becomes read-ready, call
   <xref linkend="libpq-PQconsumeInput"/>, then call
   <xref linkend="libpq-PQflush"/> again.  Repeat until
   <xref linkend="libpq-PQflush"/> returns 0.  (It is necessary to check for
   read-ready and drain the input with <xref linkend="libpq-PQconsumeInput"/>,
   because the server can block trying to send us data, e.g., NOTICE
   messages, and won't read our data until we read its.)  Once
   <xref linkend="libpq-PQflush"/> returns 0, wait for the socket to be
   read-ready and then read the response as described above.
  </para>

 </sect1>

 <sect1 id="libpq-pipeline-mode">
  <title>Pipeline Mode</title>

  <indexterm zone="libpq-pipeline-mode">
   <primary>libpq</primary>
   <secondary>pipeline mode</secondary>
  </indexterm>

  <indexterm zone="libpq-pipeline-mode">
   <primary>pipelining</primary>
   <secondary>in libpq</secondary>
  </indexterm>

  <indexterm zone="libpq-pipeline-mode">
   <primary>batch mode</primary>
   <secondary>in libpq</secondary>
  </indexterm>

  <para>
   <application>libpq</application> pipeline mode allows applications to
   send a query without having to read the result of the previously
   sent query.  Taking advantage of the pipeline mode, a client will wait
   less for the server, since multiple queries/results can be
   sent/received in a single network transaction.
  </para>

  <para>
   While pipeline mode provides a significant performance boost, writing
   clients using the pipeline mode is more complex because it involves
   managing a queue of pending queries and finding which result
   corresponds to which query in the queue.
  </para>

  <para>
   Pipeline mode also generally consumes more memory on both the client and server,
   though careful and aggressive management of the send/receive queue can mitigate
   this.  This applies whether or not the connection is in blocking or non-blocking
   mode.
  </para>

  <para>
   While <application>libpq</application>'s pipeline API was introduced in
   <productname>PostgreSQL</productname> 14, it is a client-side feature
   which doesn't require special server support and works on any server
   that supports the v3 extended query protocol.  For more information see
   <xref linkend="protocol-flow-pipelining"/>.
  </para>

  <sect2 id="libpq-pipeline-using">
   <title>Using Pipeline Mode</title>

   <para>
    To issue pipelines, the application must switch the connection
    into pipeline mode,
    which is done with <xref linkend="libpq-PQenterPipelineMode"/>.
    <xref linkend="libpq-PQpipelineStatus"/> can be used
    to test whether pipeline mode is active.
    In pipeline mode, only <link linkend="libpq-async">asynchronous operations</link>
    that utilize the extended query protocol
    are permitted, command strings containing multiple SQL commands are
    disallowed, and so is <literal>COPY</literal>.
    Using synchronous command execution functions
    such as <function>PQfn</function>,
    <function>PQexec</function>,
    <function>PQexecParams</function>,
    <function>PQprepare</function>,
    <function>PQexecPrepared</function>,
    <function>PQdescribePrepared</function>,
    <function>PQdescribePortal</function>,
    <function>PQclosePrepared</function>,
    <function>PQclosePortal</function>,
    is an error condition.
    <function>PQsendQuery</function> is
    also disallowed, because it uses the simple query protocol.
    Once all dispatched commands have had their results processed, and
    the end pipeline result has been consumed, the application may return
    to non-pipelined mode with <xref linkend="libpq-PQexitPipelineMode"/>.
   </para>

   <note>
    <para>
     It is best to use pipeline mode with <application>libpq</application> in
     <link linkend="libpq-PQsetnonblocking">non-blocking mode</link>. If used
     in blocking mode it is possible for a client/server deadlock to occur.
      <footnote>
       <para>