Re: Missing example for SAVEPOINT using the same savepoint name - Mailing list pgsql-docs

commit e921441f22bad972393144628c7ee48845d5384c
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Tue Apr 12 14:30:11 2022 +0000

    doc: Improve docs regarding savepoint name reuse
   
    Per documentation comment the savepoint command lacks an example
    where the savepoint name is reused.  The suggested example didn't
    conform to the others on the page, nor did the suggested location
    in compatibility seem desirable, but the omission rang true. Add
    another example to the examples section demonstrating this case.
    Additionally, document under the description for savepoint_name
    that we allow for the name to be repeated - and note what that
    means in terms of release and rollback. It seems desirable to
    place this comment in description rather than notes for savepoint.
    For the other two commands the behavior in the presence of
    duplicate savepoint names best fits as notes.  In fact release
    already had one.  This commit copies the same verbiage over to
    rollback.

diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml
index 3d5a241e1a..7bd1b41feb 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..fd017935ea 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,25 @@ 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; // 1, 2
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1; // just 1
+COMMIT;
+</programlisting>
+  The above transaction shows row 3 being rolled back first then row 2.
+  </para>
+
  </refsect1>
 
  <refsect1>