Skip to content

Commit efcaf1e

Browse files
tglsfdctglsfdc
committed
Some mop-up work for savepoints (nested transactions). Store a small
number of active subtransaction XIDs in each backend's PGPROC entry, and use this to avoid expensive probes into pg_subtrans during TransactionIdIsInProgress. Extend EOXactCallback API to allow add-on modules to get control at subxact start/end. (This is deliberately not compatible with the former API, since any uses of that API probably need manual review anyway.) Add basic reference documentation for SAVEPOINT and related commands. Minor other cleanups to check off some of the open issues for subtransactions. Alvaro Herrera and Tom Lane.
1 parent 9d9cdf8 commit efcaf1e

File tree

23 files changed

+1055
-282
lines changed

23 files changed

+1055
-282
lines changed

‎doc/src/sgml/advanced.sgml

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.41 2004/03/31 16:20:53 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.42 2004/08/01 17:32:11 tgl Exp $
33
-->
44

55
<chapter id="tutorial-advanced">
@@ -257,6 +257,64 @@ COMMIT;
257257
you are using.
258258
</para>
259259
</note>
260+
261+
<para>
262+
It's possible to control the statements in a transaction in a more
263+
granular fashion through the use of <firstterm>savepoints</>. Savepoints
264+
allow you to selectively discard parts of the transaction, while
265+
committing the rest. After defining a savepoint with
266+
<command>SAVEPOINT</>, you can if needed roll back to the savepoint
267+
with <command>ROLLBACK TO</>. All the transaction's database changes
268+
between defining the savepoint and rolling back to it are discarded, but
269+
changes earlier than the savepoint are kept.
270+
</para>
271+
272+
<para>
273+
After rolling back to a savepoint, it continues to be defined, so you can
274+
roll back to it several times. Conversely, if you are sure you won't need
275+
to roll back to a particular savepoint again, it can be released, so the
276+
system can free some resources. Keep in mind that either releasing or
277+
rolling back to a savepoint
278+
will automatically release all savepoints that were defined after it.
279+
</para>
280+
281+
<para>
282+
All this is happening within the transaction block, so none of it
283+
is visible to other database sessions. When and if you commit the
284+
transaction block, the committed actions become visible as a unit
285+
to other sessions, while the rolled-back actions never become visible
286+
at all.
287+
</para>
288+
289+
<para>
290+
Remembering the bank database, suppose we debit $100.00 from Alice's
291+
account, and credit Bob's account, only to find later that we should
292+
have credited Wally's account. We could do it using savepoints like
293+
294+
<programlisting>
295+
BEGIN;
296+
UPDATE accounts SET balance = balance - 100.00
297+
WHERE name = 'Alice';
298+
SAVEPOINT my_savepoint;
299+
UPDATE accounts SET balance = balance + 100.00
300+
WHERE name = 'Bob';
301+
-- oops ... forget that and use Wally's account
302+
ROLLBACK TO my_savepoint;
303+
UPDATE accounts SET balance = balance + 100.00
304+
WHERE name = 'Wally';
305+
COMMIT;
306+
</programlisting>
307+
</para>
308+
309+
<para>
310+
This example is, of course, oversimplified, but there's a lot of control
311+
to be had over a transaction block through the use of savepoints.
312+
Moreover, <command>ROLLBACK TO</> is the only way to regain control of a
313+
transaction block that was put in aborted state by the
314+
system due to an error, short of rolling it back completely and starting
315+
again.
316+
</para>
317+
260318
</sect1>
261319

262320

‎doc/src/sgml/ref/allfiles.sgml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.59 2004/06/25 21:55:50 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.60 2004/08/01 17:32:13 tgl Exp $
33
PostgreSQL documentation
44
Complete list of usable sgml source files in this directory.
55
-->
@@ -88,9 +88,12 @@ Complete list of usable sgml source files in this directory.
8888
<!entity notify system "notify.sgml">
8989
<!entity prepare system "prepare.sgml">
9090
<!entity reindex system "reindex.sgml">
91+
<!entity releaseSavepoint system "release.sgml">
9192
<!entity reset system "reset.sgml">
9293
<!entity revoke system "revoke.sgml">
9394
<!entity rollback system "rollback.sgml">
95+
<!entity rollbackTo system "rollback_to.sgml">
96+
<!entity savepoint system "savepoint.sgml">
9497
<!entity select system "select.sgml">
9598
<!entity selectInto system "select_into.sgml">
9699
<!entity set system "set.sgml">

‎doc/src/sgml/ref/begin.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.30 2004/01/11 09:24:17 petere Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.31 2004/08/01 17:32:13 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -31,7 +31,7 @@ BEGIN [ WORK | TRANSACTION ]
3131

3232
<para>
3333
<command>BEGIN</command> initiates a transaction block, that is,
34-
all statements after <command>BEGIN</command> command will be
34+
all statements after a <command>BEGIN</command> command will be
3535
executed in a single transaction until an explicit <xref
3636
linkend="sql-commit" endterm="sql-commit-title"> or <xref
3737
linkend="sql-rollback" endterm="sql-rollback-title"> is given.
@@ -145,6 +145,7 @@ BEGIN;
145145
<member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
146146
<member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
147147
<member><xref linkend="sql-start-transaction" endterm="sql-start-transaction-title"></member>
148+
<member><xref linkend="sql-savepoint" endterm="sql-savepoint-title"></member>
148149
</simplelist>
149150
</refsect1>
150151
</refentry>

‎doc/src/sgml/ref/release.sgml

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<!--
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/release.sgml,v 1.1 2004/08/01 17:32:13 tgl Exp $
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="SQL-RELEASE">
7+
<refmeta>
8+
<refentrytitle id="SQL-RELEASE-TITLE">RELEASE</refentrytitle>
9+
<refmiscinfo>SQL - Language Statements</refmiscinfo>
10+
</refmeta>
11+
12+
<refnamediv>
13+
<refname>RELEASE</refname>
14+
<refpurpose>destroy a previously defined savepoint</refpurpose>
15+
</refnamediv>
16+
17+
<indexterm zone="sql-release">
18+
<primary>RELEASE</primary>
19+
</indexterm>
20+
21+
<indexterm zone="sql-release">
22+
<primary>savepoints</primary>
23+
<secondary>releasing</secondary>
24+
</indexterm>
25+
26+
<refsynopsisdiv>
27+
<synopsis>
28+
RELEASE <replaceable>savepoint_name</replaceable>
29+
</synopsis>
30+
</refsynopsisdiv>
31+
32+
<refsect1>
33+
<title>Description</title>
34+
35+
<para>
36+
<command>RELEASE</command> destroys a savepoint previously defined
37+
in the current transaction.
38+
</para>
39+
40+
<para>
41+
Destroying a savepoint makes it unavailable as a rollback point,
42+
but it has no other user visible behavior. It does not undo the
43+
effects of commands executed after the savepoint was established.
44+
(To do that, see <xref linkend="sql-rollback-to"
45+
endterm="sql-rollback-to-title">.) Destroying a savepoint when
46+
it is no longer needed may allow the system to reclaim some resources
47+
earlier than transaction end.
48+
</para>
49+
50+
<para>
51+
<command>RELEASE</command> also destroys all savepoints that were
52+
established after the named savepoint was established.
53+
</para>
54+
</refsect1>
55+
56+
<refsect1>
57+
<title>Parameters</title>
58+
59+
<variablelist>
60+
<varlistentry>
61+
<term><replaceable>savepoint_name</replaceable></term>
62+
<listitem>
63+
<para>
64+
The name of the savepoint to destroy.
65+
</para>
66+
</listitem>
67+
</varlistentry>
68+
</variablelist>
69+
</refsect1>
70+
71+
<refsect1>
72+
<title>Notes</title>
73+
74+
<para>
75+
Specifying a savepoint name that was not previously defined is an error.
76+
</para>
77+
78+
<para>
79+
It is not possible to release a savepoint when the transaction is in
80+
aborted state.
81+
</para>
82+
83+
<para>
84+
If multiple savepoints have the same name, only the one that was most
85+
recently defined is released.
86+
</para>
87+
88+
</refsect1>
89+
90+
<refsect1>
91+
<title>Examples</title>
92+
93+
<para>
94+
To establish and later destroy a savepoint:
95+
<programlisting>
96+
BEGIN;
97+
INSERT INTO table VALUES (3);
98+
SAVEPOINT my_savepoint;
99+
INSERT INTO table VALUES (4);
100+
RELEASE my_savepoint;
101+
COMMIT;
102+
</programlisting>
103+
The above transaction will insert both 3 and 4.
104+
</para>
105+
</refsect1>
106+
107+
<refsect1>
108+
<title>Compatibility</title>
109+
110+
<para>
111+
RELEASE is fully conforming to the SQL standard.
112+
</para>
113+
</refsect1>
114+
115+
<refsect1>
116+
<title>See Also</title>
117+
118+
<simplelist type="inline">
119+
<member><xref linkend="sql-begin" endterm="sql-begin-title"></member>
120+
<member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
121+
<member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
122+
<member><xref linkend="sql-rollback-to" endterm="sql-rollback-to-title"></member>
123+
<member><xref linkend="sql-savepoint" endterm="sql-savepoint-title"></member>
124+
</simplelist>
125+
</refsect1>
126+
</refentry>
127+
128+
<!-- Keep this comment at the end of the file
129+
Local variables:
130+
mode: sgml
131+
sgml-omittag:nil
132+
sgml-shorttag:t
133+
sgml-minimize-attributes:nil
134+
sgml-always-quote-attributes:t
135+
sgml-indent-step:1
136+
sgml-indent-data:t
137+
sgml-parent-document:nil
138+
sgml-default-dtd-file:"../reference.ced"
139+
sgml-exposed-tags:nil
140+
sgml-local-catalogs:"/usr/lib/sgml/catalog"
141+
sgml-local-ecat-files:nil
142+
End:
143+
-->

‎doc/src/sgml/ref/rollback.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/rollback.sgml,v 1.17 2003/11/29 19:51:39 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/rollback.sgml,v 1.18 2004/08/01 17:32:13 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -90,6 +90,7 @@ ROLLBACK;
9090
<simplelist type="inline">
9191
<member><xref linkend="sql-begin" endterm="sql-begin-title"></member>
9292
<member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
93+
<member><xref linkend="sql-rollback-to" endterm="sql-rollback-to-title"></member>
9394
</simplelist>
9495
</refsect1>
9596
</refentry>

0 commit comments

Comments
 (0)