summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/ref/savepoint.sgml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:15:05 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:15:05 +0000
commit46651ce6fe013220ed397add242004d764fc0153 (patch)
tree6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/ref/savepoint.sgml
parentInitial commit. (diff)
downloadpostgresql-14-46651ce6fe013220ed397add242004d764fc0153.tar.xz
postgresql-14-46651ce6fe013220ed397add242004d764fc0153.zip
Adding upstream version 14.5.upstream/14.5upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/ref/savepoint.sgml')
-rw-r--r--doc/src/sgml/ref/savepoint.sgml165
1 files changed, 165 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml
new file mode 100644
index 0000000..f84ac3d
--- /dev/null
+++ b/doc/src/sgml/ref/savepoint.sgml
@@ -0,0 +1,165 @@
+<!--
+doc/src/sgml/ref/savepoint.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="sql-savepoint">
+ <indexterm zone="sql-savepoint">
+ <primary>SAVEPOINT</primary>
+ </indexterm>
+
+ <indexterm zone="sql-savepoint">
+ <primary>savepoints</primary>
+ <secondary>defining</secondary>
+ </indexterm>
+
+ <refmeta>
+ <refentrytitle>SAVEPOINT</refentrytitle>
+ <manvolnum>7</manvolnum>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>SAVEPOINT</refname>
+ <refpurpose>define a new savepoint within the current transaction</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+SAVEPOINT <replaceable>savepoint_name</replaceable>
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ <command>SAVEPOINT</command> establishes a new savepoint within
+ the current transaction.
+ </para>
+
+ <para>
+ A savepoint is a special mark inside a transaction that allows all commands
+ that are executed after it was established to be rolled back, restoring
+ the transaction state to what it was at the time of the savepoint.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>savepoint_name</replaceable></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>
+ Use <link linkend="sql-rollback-to"><command>ROLLBACK TO</command></link> to
+ rollback to a savepoint. Use <link linkend="sql-release-savepoint"><command>RELEASE SAVEPOINT</command></link>
+ to destroy a savepoint, keeping
+ the effects of commands executed after it was established.
+ </para>
+
+ <para>
+ Savepoints can only be established when inside a transaction block.
+ There can be multiple savepoints defined within a transaction.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>
+ To establish a savepoint and later undo the effects of all commands executed
+ after it was established:
+<programlisting>
+BEGIN;
+ INSERT INTO table1 VALUES (1);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (2);
+ ROLLBACK TO SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (3);
+COMMIT;
+</programlisting>
+ The above transaction will insert the values 1 and 3, but not 2.
+ </para>
+
+ <para>
+ To establish and later destroy a savepoint:
+<programlisting>
+BEGIN;
+ INSERT INTO table1 VALUES (3);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (4);
+ RELEASE SAVEPOINT my_savepoint;
+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 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;
+</programlisting>
+ The above transaction shows row 3 being rolled back first, then row 2.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Compatibility</title>
+
+ <para>
+ SQL requires a savepoint to be destroyed automatically when another
+ savepoint with the same name is established. In
+ <productname>PostgreSQL</productname>, the old savepoint is kept, though only the more
+ recent one will be used when rolling back or releasing. (Releasing the
+ newer savepoint with <command>RELEASE SAVEPOINT</command> will cause the older one
+ to again become accessible to <command>ROLLBACK TO SAVEPOINT</command> and
+ <command>RELEASE SAVEPOINT</command>.) Otherwise, <command>SAVEPOINT</command> is
+ fully SQL conforming.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-begin"/></member>
+ <member><xref linkend="sql-commit"/></member>
+ <member><xref linkend="sql-release-savepoint"/></member>
+ <member><xref linkend="sql-rollback"/></member>
+ <member><xref linkend="sql-rollback-to"/></member>
+ </simplelist>
+ </refsect1>
+</refentry>