Doc: minor improvements for plpgsql "Transaction Management" section.

Point out that savepoint commands cannot be issued in PL/pgSQL,
and suggest that exception blocks can usually be used instead.

Add a caveat to the discussion of cursor loops vs. transactions,
pointing out that any locks taken by the cursor query will be lost
at COMMIT.  This is implicit in what's already said, but the existing
text leaves the distinct impression that the auto-hold behavior is
transparent, which it's not really.

Per a couple of recent complaints (one unsigned, and one in bug #18531
from Dzmitry Jachnik).  Back-patch to v17, just so this makes it into
current docs in less than a year-and-a-half.

Discussion: https://postgr.es/m/172076354433.736586.14347210271966220018@wrigleys.postgresql.org
Discussion: https://postgr.es/m/18531-c6dddd33b8555fd2@postgresql.org

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f88d680e2996f9fc6ceb29016dd043c..071f5a87d3b0c8aceb3a3b5e233de092a2c980c6 100644 (file)
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3745,6 +3745,17 @@ CALL transaction_test1();
     <command>SELECT</command> in between.
    </para>
 
+   <para>
+    <application>PL/pgSQL</application> does not support savepoints
+    (<command>SAVEPOINT</command>/<command>ROLLBACK TO
+    SAVEPOINT</command>/<command>RELEASE SAVEPOINT</command> commands).
+    Typical usage patterns for savepoints can be replaced by blocks with
+    exception handlers (see <xref linkend="plpgsql-error-trapping"/>).
+    Under the hood, a block with exception handlers forms a
+    subtransaction, which means that transactions cannot be ended inside
+    such a block.
+   </para>
+
    <para>
     Special considerations apply to cursor loops.  Consider this example:
 <programlisting>
@@ -3770,7 +3781,10 @@ CALL transaction_test2();
     evaluated at the first <command>COMMIT</command> or
     <command>ROLLBACK</command> rather than row by row.  The cursor is still
     removed automatically after the loop, so this is mostly invisible to the
-    user.
+    user.  But one must keep in mind that any table or row locks taken by
+    the cursor's query will no longer be held after the
+    first <command>COMMIT</command> or
+    <command>ROLLBACK</command>.
    </para>
 
    <para>
@@ -3778,10 +3792,6 @@ CALL transaction_test2();
     that are not read-only (for example <command>UPDATE
     ... RETURNING</command>).
    </para>
-
-   <para>
-    A transaction cannot be ended inside a block with exception handlers.
-   </para>
   </sect1>
 
   <sect1 id="plpgsql-errors-and-messages">