docs: split/reshuffle pipeline docs

- Postgres concept
- Psycopg usage
- detail about sync points
- disclaimer - don't call the semver police.

diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst
index 7f01d17aac62888fcbc6057fe9d21b58f1f2d466..d7613b12c474227e52f94dca653b3123fee26044 100644 (file)
--- a/docs/advanced/pipeline.rst
+++ b/docs/advanced/pipeline.rst
@@ -13,16 +13,6 @@ 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 roundtrip.
 Pipeline mode can provide a significant performance boost to the application.
 
-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. Note that results are
-buffered on the server side; the server flushes that buffer when a
-*synchronization point* is established. 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; a
-`~errors.PipelineAborted` exception is raised for each such command. Query
-processing resumes after the synchronization point.
-
 Pipeline mode is most useful when the server is distant, i.e., network latency
 (“ping time”) is high, and also when many small operations are being performed
 in rapid succession. There is usually less benefit in using pipelined commands
@@ -32,10 +22,11 @@ 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.
 
-The pipeline mode is available on any currently supported PostgreSQL version
-but, in order to make use of it, the client must use a libpq from PostgreSQL
-14 or higher. You can use `Pipeline.is_supported()` to make sure your client
-has the right library.
+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. Note that results are
+buffered on the server side; the server flushes that buffer when a
+:ref:`synchronization point <pipeline-sync>` is established.
 
 .. seealso:: The `PostgreSQL pipeline mode documentation`__ contains many
     details around when it is most useful to use the pipeline mode and about
@@ -43,6 +34,12 @@ has the right library.
 
     .. __: https://www.postgresql.org/docs/current/libpq-pipeline-mode.html
 
+
+.. _pipeline-usage:
+
+Pipeline mode usage
+-------------------
+
 Psycopg supports the pipeline mode via the `Connection.pipeline()` method. The
 method is a context manager: at the end of the ``with`` block, the connection
 resumes the normal operation mode.
@@ -53,8 +50,40 @@ normal mode, Psycopg will not wait for the server to receive the result of
 each query, which will be received in batches when the server flushes it
 output buffer.
 
-This flush can happen either when a synchronization point is established by
-Psycopg:
+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()`.
+
+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 :ref:`synchronization point <pipeline-sync>`; a `~errors.PipelineAborted`
+exception is raised for each such command. Query processing resumes after the
+synchronization point.
+
+.. warning::
+
+    Certain features are not available in pipeline mode, including:
+
+    - COPY is not supported in pipeline mode by PostgreSQL.
+    - `Cursor.stream()` doesn't make sense in pipeline mode (its job is the
+      opposite of batching!)
+    - `ServerCursor` are currently not implemented in pipeline mode.
+
+.. note::
+
+    Starting from Psycopg 3.1, `~Cursor.executemany()` makes use internally of
+    the pipeline mode; as a consequence there is no need to handle a pipeline
+    block just to call `!executemany()` once.
+
+
+.. _pipeline-sync:
+
+Synchronization points
+----------------------
+
+Flushing query results to the client can happen either when a synchronization
+point is established by Psycopg:
 
 - using the `Pipeline.sync()` method,
 - on `~Connection.rollback()`,
@@ -68,12 +97,12 @@ output buffer is full.
 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()`.
+
+The fine prints
+---------------
 
 .. warning::
+
     The Pipeline mode is an experimental feature.
 
     Its behaviour, especially around error condtions, hasn't been explored as
@@ -84,14 +113,7 @@ in their execution order, using `~Cursor.nextset()`.
     bugs and shortcomings forcing us to change the current interface or
     behaviour.
 
-.. warning::
-    Certain features are not available in pipeline mode, including:
-
-    - COPY is not supported in pipeline mode by PostgreSQL.
-    - `Cursor.stream()` doesn't make sense in pipeline mode (its job is the
-      opposite of batching!)
-    - `ServerCursor` are currently not implemented in pipeline mode.
-
-.. note::
-    Starting from Psycopg 3.1, `Cursor.executemany()` is optimised to make use
-    of pipeline mode.
+The pipeline mode is available on any currently supported PostgreSQL version,
+but, in order to make use of it, the client must use a libpq from PostgreSQL
+14 or higher. You can use `Pipeline.is_supported()` to make sure your client
+has the right library.