From 064b323a6ddf33bd7dc4af7be2c173fb1f6fb8d8 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Sun, 3 Apr 2022 21:59:55 +0200 Subject: [PATCH] docs: clarify flush and sync pipeline operations --- docs/advanced/pipeline.rst | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst index 21a51fa9e..423ef1fa0 100644 --- a/docs/advanced/pipeline.rst +++ b/docs/advanced/pipeline.rst @@ -51,22 +51,27 @@ resumes the normal operation mode. Within the pipeline block, you can use one or more cursors to execute several operations, using `~Cursor.execute()` and `~Cursor.executemany()`. Unlike in normal mode, Psycopg will not wait for the server to receive the result of -each query, which will be received in batches when a synchronization point is -established. +each query, which will be received in batches when the server flushes it +output buffer. -Psycopg can establish a synchronization point: +This flush can happen either when a synchronization point is established by +Psycopg: -- using the `Pipeline.sync()` method; +- using the `Pipeline.sync()` method, or, - at the end of a `!Pipeline` block; -- using a fetch method such as `Cursor.fetchone()`. -The server might perform a sync on its own initiative, for instance when the +or using a fetch method such as `Cursor.fetchone()`. + +The server might perform a flush on its own initiative, for instance when the output buffer is full. -When a sync is performed, all the pending results are sent back to the cursors -which executed them. If a cursor had run more than one query, it will receive -more than one result; results after the first will be available, in their -execution order, using `~Cursor.nextset()`. +In contrast with a synchronization point, a flush request (i.e. calling a +fetch method) will not reset the pipeline error state. + +When a flush (or a sync) is performed, all pending results are sent back to +the cursors which executed them. If a cursor had run more than one query, it +will receive more than one result; results after the first will be available, +in their execution order, using `~Cursor.nextset()`. .. warning:: Certain features are not available in pipeline mode, including: -- 2.47.2