Debian Codegraph @

doc/src/sgml/ref/release_savepoint.sgml

raw
1 <!--
2 doc/src/sgml/ref/release_savepoint.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-release-savepoint">
7 <indexterm zone="sql-release-savepoint">
8 <primary>RELEASE SAVEPOINT</primary>
9 </indexterm>
10
11 <indexterm zone="sql-release-savepoint">
12 <primary>savepoints</primary>
13 <secondary>releasing</secondary>
14 </indexterm>
15
16 <refmeta>
17 <refentrytitle>RELEASE SAVEPOINT</refentrytitle>
18 <manvolnum>7</manvolnum>
19 <refmiscinfo>SQL - Language Statements</refmiscinfo>
20 </refmeta>
21
22 <refnamediv>
23 <refname>RELEASE SAVEPOINT</refname>
24 <refpurpose>release a previously defined savepoint</refpurpose>
25 </refnamediv>
26
27 <refsynopsisdiv>
28 <synopsis>
29 RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
30 </synopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Description</title>
35
36 <para>
37 <command>RELEASE SAVEPOINT</command> releases the named savepoint and
38 all active savepoints that were created after the named savepoint,
39 and frees their resources. All changes made since the creation of
40 the savepoint that didn't already get rolled back are merged into
41 the transaction or savepoint that was active when the named savepoint
42 was created. Changes made after <command>RELEASE SAVEPOINT</command>
43 will also be part of this active transaction or savepoint.
44 </para>
45 </refsect1>
46
47 <refsect1>
48 <title>Parameters</title>
49
50 <variablelist>
51 <varlistentry>
52 <term><replaceable>savepoint_name</replaceable></term>
53 <listitem>
54 <para>
55 The name of the savepoint to release.
56 </para>
57 </listitem>
58 </varlistentry>
59 </variablelist>
60 </refsect1>
61
62 <refsect1>
63 <title>Notes</title>
64
65 <para>
66 Specifying a savepoint name that was not previously defined is an error.
67 </para>
68
69 <para>
70 It is not possible to release a savepoint when the transaction is in
71 an aborted state; to do that, use <xref linkend="sql-rollback-to"/>.
72 </para>
73
74 <para>
75 If multiple savepoints have the same name, only the most recently defined
76 unreleased one is released. Repeated commands will release progressively
77 older savepoints.
78 </para>
79
80 </refsect1>
81
82 <refsect1>
83 <title>Examples</title>
84
85 <para>
86 To establish and later release a savepoint:
87 <programlisting>
88 BEGIN;
89 INSERT INTO table1 VALUES (3);
90 SAVEPOINT my_savepoint;
91 INSERT INTO table1 VALUES (4);
92 RELEASE SAVEPOINT my_savepoint;
93 COMMIT;
94 </programlisting>
95 The above transaction will insert both 3 and 4.
96 </para>
97
98 <para>
99 A more complex example with multiple nested subtransactions:
100 <programlisting>
101 BEGIN;
102 INSERT INTO table1 VALUES (1);
103 SAVEPOINT sp1;
104 INSERT INTO table1 VALUES (2);
105 SAVEPOINT sp2;
106 INSERT INTO table1 VALUES (3);
107 RELEASE SAVEPOINT sp2;
108 INSERT INTO table1 VALUES (4))); -- generates an error
109 </programlisting>
110 In this example, the application requests the release of the savepoint
111 <literal>sp2</literal>, which inserted 3. This changes the insert's
112 transaction context to <literal>sp1</literal>. When the statement
113 attempting to insert value 4 generates an error, the insertion of 2 and
114 4 are lost because they are in the same, now-rolled back savepoint,
115 and value 3 is in the same transaction context. The application can
116 now only choose one of these two commands, since all other commands
117 will be ignored:
118 <programlisting>
119 ROLLBACK;
120 ROLLBACK TO SAVEPOINT sp1;
121 </programlisting>
122 Choosing <command>ROLLBACK</command> will abort everything, including
123 value 1, whereas <command>ROLLBACK TO SAVEPOINT sp1</command> will retain
124 value 1 and allow the transaction to continue.
125 </para>
126
127 </refsect1>
128
129 <refsect1>
130 <title>Compatibility</title>
131
132 <para>
133 This command conforms to the <acronym>SQL</acronym> standard. The standard
134 specifies that the key word <literal>SAVEPOINT</literal> is
135 mandatory, but <productname>PostgreSQL</productname> allows it to
136 be omitted.
137 </para>
138 </refsect1>
139
140 <refsect1>
141 <title>See Also</title>
142
143 <simplelist type="inline">
144 <member><xref linkend="sql-begin"/></member>
145 <member><xref linkend="sql-commit"/></member>
146 <member><xref linkend="sql-rollback"/></member>
147 <member><xref linkend="sql-rollback-to"/></member>
148 <member><xref linkend="sql-savepoint"/></member>
149 </simplelist>
150 </refsect1>
151 </refentry>