doc: clarify the behavior of identically-named savepoints

Original patch by David G. Johnston.

Reported-by: David G. Johnston
Discussion: https://postgr.es/m/CAKFQuwYQCxSSuSL18skCWG8QHFswOJ3hjovHsOZUE346i4OpVQ@mail.gmail.com

Backpatch-through: 10

diff --git a/doc/src/sgml/ref/release_savepoint.sgml b/doc/src/sgml/ref/release_savepoint.sgml
index 39665d28efad03f5a5c8bebc701d534bb2e57b9b..daf8eb9a4364ae52f36949e194d2e565299443a8 100644 (file)
--- a/doc/src/sgml/ref/release_savepoint.sgml
+++ b/doc/src/sgml/ref/release_savepoint.sgml
@@ -82,8 +82,9 @@ RELEASE [ SAVEPOINT ] savepoint_name
   
 
   
-   If multiple savepoints have the same name, only the one that was most
-   recently defined is released.
+   If multiple savepoints have the same name, only the most recently defined
+   unreleased one is released.  Repeated commands will release progressively
+   older savepoints.
   
 
  

diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml
index b17342a1ee6a55c4a3d18d30ef7203ad54d2e7ae..f84ac3d167f4a7201cce59c98046f6b7f56894da 100644 (file)
--- a/doc/src/sgml/ref/savepoint.sgml
+++ b/doc/src/sgml/ref/savepoint.sgml
@@ -53,7 +53,9 @@ SAVEPOINT savepoint_name
     savepoint_name
     
      
-      The name to give to the new savepoint.
+      The name to give to the new savepoint.  If savepoints with the
+      same name already exist, they will be inaccessible until newer
+      identically-named savepoints are released.
      
     
    
@@ -106,6 +108,32 @@ COMMIT;
 
    The above transaction will insert both 3 and 4.
   
+
+  
+  To use a single savepoint name:
+
+BEGIN;
+    INSERT INTO table1 VALUES (1);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (2);
+    SAVEPOINT my_savepoint;
+    INSERT INTO table1 VALUES (3);
+
+    -- rollback to the second savepoint
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1;               -- shows rows 1 and 2
+
+    -- release the second savepoint
+    RELEASE SAVEPOINT my_savepoint;
+
+    -- rollback to the first savepoint
+    ROLLBACK TO SAVEPOINT my_savepoint;
+    SELECT * FROM table1;               -- shows only row 1
+COMMIT;
+
+  The above transaction shows row 3 being rolled back first, then row 2.
+  
+