Date: Wed, 23 Jun 2021 12:55:40 -0400
From: Alvaro Herrera <alvaro.herrera@2ndquadrant.com>
To: Boris Kolpackov <boris@codesynthesis.com>
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: Pipeline mode and PQpipelineSync()
Message-ID: <202106231655.5tkagqvcxej5@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ub2kcidd5j7isxn3"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <boris.20210623125826@codesynthesis.com>
Archived-At: 
 <https://www.postgresql.org/message-id/202106231655.5tkagqvcxej5%40alvherre.pgsql>
Precedence: bulk


--ub2kcidd5j7isxn3
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On 2021-Jun-23, Boris Kolpackov wrote:

> I think one change that is definitely needed is to make it clear that
> the PQpipelineSync() call is not optional.
> 
> I would also add a note saying that while the server starts processing
> the pipeline immediately, it may buffer the results and the only way
> to flush them out is to call PQpipelineSync().

Aren't those two things one and the same?  I propose the attached.

-- 
Álvaro Herrera       Valdivia, Chile
"El hombre nunca sabe de lo que es capaz hasta que lo intenta" (C. Dickens)

--ub2kcidd5j7isxn3
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
	filename="0001-Clarify-that-pipeline-sync-is-mandatory.patch"

From d9c2b07d7ef8d85ae387fdf6c9a04bf2c712b6fc Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Wed, 23 Jun 2021 12:40:15 -0400
Subject: [PATCH] Clarify that pipeline sync is mandatory

---
 doc/src/sgml/libpq.sgml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 441cc0da3a..0217f8d8c7 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5103,10 +5103,12 @@ int PQflush(PGconn *conn);
      The server executes statements, and returns results, in the order the
      client sends them.  The server will begin executing the commands in the
      pipeline immediately, not waiting for the end of the pipeline.
+     Do note that results are buffered on the server side; a synchronization
+     point, establshied with <function>PQpipelineSync</function>, is necessary
+     in order for all results to be flushed to the client.
      If any statement encounters an error, the server aborts the current
      transaction and does not execute any subsequent command in the queue
-     until the next synchronization point established by
-     <function>PQpipelineSync</function>;
+     until the next synchronization point;
      a <literal>PGRES_PIPELINE_ABORTED</literal> result is produced for
      each such command.
      (This remains true even if the commands in the pipeline would rollback
-- 
2.20.1


--ub2kcidd5j7isxn3--