On Fri, Oct 14, 2022 at 05:46:55PM -0400, Robert Treat wrote:
> On Fri, Oct 14, 2022 at 3:51 PM Bruce Momjian <br...@momjian.us> wrote:
> > Attached is the merged patch from all the great comments I received. I
> > have also rebuilt the docs with the updated patch:
> >
> > https://momjian.us/tmp/pgsql/
> >
>
> + <command>RELEASE SAVEPOINT</command> also subcommits and destroys
> + all savepoints that were established after the named savepoint was
> + established. This means that any subtransactions of the named savepoint
> + will also be subcommitted and destroyed.
>
> Wonder if we should be more explicit that data changes are preserved,
> not destroyed... something like:
> "This means that any changes within subtransactions of the named
> savepoint will be subcommitted and those subtransactions will be
> destroyed."
Good point. I reread the section and there was just too much confusion
over subtransactions, partly because the behavior just doesn't map
easily to subtransaction. I therefore merged all three paragraphs into
one and tried to make the text saner; release_savepoint.sgml diff
attached, URL content updated.
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
diff --git a/doc/src/sgml/ref/release_savepoint.sgml b/doc/src/sgml/ref/release_savepoint.sgml
index daf8eb9a43..ae603ad102 100644
--- a/doc/src/sgml/ref/release_savepoint.sgml
+++ b/doc/src/sgml/ref/release_savepoint.sgml
@@ -34,23 +34,14 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
<title>Description</title>
<para>
- <command>RELEASE SAVEPOINT</command> destroys a savepoint previously defined
- in the current transaction.
- </para>
-
- <para>
- Destroying a savepoint makes it unavailable as a rollback point,
- but it has no other user visible behavior. It does not undo the
- effects of commands executed after the savepoint was established.
- (To do that, see <xref linkend="sql-rollback-to"/>.)
- Destroying a savepoint when
- it is no longer needed allows the system to reclaim some resources
- earlier than transaction end.
- </para>
-
- <para>
- <command>RELEASE SAVEPOINT</command> also destroys all savepoints that were
- established after the named savepoint was established.
+ <command>RELEASE SAVEPOINT</command> destroys the named savepoint and
+ all active savepoints that were created after the named savepoint.
+ All changes made since the creation of the savepoint, excluding rolled
+ back savepoints changes, are treated as part of the transaction
+ or savepoint that was active when the named savepoint was created.
+ Changes made after <command>RELEASE SAVEPOINT</command> will be in
+ the same transaction, and have the same transaction id, as changes
+ made before the named savepoint was created.
</para>
</refsect1>
@@ -78,7 +69,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
<para>
It is not possible to release a savepoint when the transaction is in
- an aborted state.
+ an aborted state, to do that use <xref linkend="sql-rollback-to"/>.
</para>
<para>
@@ -104,6 +95,36 @@ COMMIT;
</programlisting>
The above transaction will insert both 3 and 4.
</para>
+
+ <para>
+ A more complex example with multiple nested subtransactions:
+<programlisting>
+BEGIN;
+ INSERT INTO table1 VALUES (1);
+ SAVEPOINT sp1;
+ INSERT INTO table1 VALUES (2);
+ SAVEPOINT sp2;
+ INSERT INTO table1 VALUES (3);
+ RELEASE SAVEPOINT sp2;
+ INSERT INTO table1 VALUES (4))); -- generates an error
+</programlisting>
+ In this example, the application requests the release of the savepoint
+ <literal>sp2</literal>, which inserted 3. This changes the insert's
+ transaction context to <literal>sp1</literal>. When the statement
+ attempting to insert value 4 generates an error, the insertion of 2 and
+ 4 are lost because they are in the same, now-rolled back savepoint,
+ and value 3 is in the same transaction context. The application can
+ now only choose one of these two commands, since all other commands
+ will be ignored with a warning:
+<programlisting>
+ ROLLBACK;
+ ROLLBACK TO SAVEPOINT sp1;
+</programlisting>
+ Choosing <command>ROLLBACK</command> will abort everything, including
+ value 1, whereas <command>ROLLBACK TO SAVEPOINT sp1</command> will retain
+ value 1 and allow the transaction to continue.
+ </para>
+
</refsect1>
<refsect1>
