From 233992eaed000080104cb21e562599baa3ee3655 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Thu, 9 Jun 2022 15:11:41 +0000
Subject: [PATCH] doc: Clarify Savepoint behavior around repeated name

---
 doc/src/sgml/ref/rollback_to.sgml |  6 ++++++
 doc/src/sgml/ref/savepoint.sgml   | 27 ++++++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml
index 27fa95cd1b..20a8323a13 100644
--- a/doc/src/sgml/ref/rollback_to.sgml
+++ b/doc/src/sgml/ref/rollback_to.sgml
@@ -89,6 +89,12 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re
    cannot-execute state, so while the transaction can be restored using
    <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used.
   </para>
+
+  <para>
+   If multiple savepoints have the same name, only the one that was most
+   recently defined is released.
+  </para>
+
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml
index b17342a1ee..931236eabf 100644
--- a/doc/src/sgml/ref/savepoint.sgml
+++ b/doc/src/sgml/ref/savepoint.sgml
@@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name</replaceable>
     <term><replaceable>savepoint_name</replaceable></term>
     <listitem>
      <para>
-      The name to give to the new savepoint.
+      The name to give to the new savepoint.  The name may already exist,
+      in which case a rollback or release to the same name will use the
+      one that was most recently defined.
      </para>
     </listitem>
    </varlistentry>
@@ -106,6 +108,29 @@ COMMIT;
 </programlisting>
    The above transaction will insert both 3 and 4.
   </para>
+
+  <para>
+  To use a single savepoint name:
+<programlisting>
+BEGIN;
+    INSERT INTO table1 VALUES (1);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (2);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (3);
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1;               -- shows rows 1, 2
+
+    -- gets rid of the latest savepoint without rolling back anything
+    RELEASE SAVEPOINT my_savepoint;
+
+    ROLLBACK TO SAVEPOINT my_savepoint; -- rolls back to the earliest one
+    SELECT * FROM table1;               -- shows row 1 only
+COMMIT;
+</programlisting>
+  The above transaction shows row 3 being rolled back first then row 2.
+  </para>
+
  </refsect1>
 
  <refsect1>
-- 
2.25.1