From a0899c0a97d19b0c330ff885af4b78b3e7efb100 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 15 Jul 2024 11:59:43 -0400
Subject: [PATCH] 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
---
 doc/src/sgml/plpgsql.sgml | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f8..071f5a87d3b 100644
--- 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">