granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/release_savepoint.sgml

   1 <!--
   2 doc/src/sgml/ref/release_savepoint.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-RELEASE-SAVEPOINT">
   7  <refmeta>
   8   <refentrytitle>RELEASE SAVEPOINT</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>RELEASE SAVEPOINT</refname>
  15   <refpurpose>destroy a previously defined savepoint</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-release-savepoint">
  19   <primary>RELEASE SAVEPOINT</primary>
  20  </indexterm>
  21
  22  <indexterm zone="sql-release-savepoint">
  23   <primary>savepoints</primary>
  24   <secondary>releasing</secondary>
  25  </indexterm>
  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> destroys a savepoint previously defined
  38    in the current transaction.
  39   </para>
  40
  41   <para>
  42    Destroying a savepoint makes it unavailable as a rollback point,
  43    but it has no other user visible behavior.  It does not undo the
  44    effects of commands executed after the savepoint was established.
  45    (To do that, see <xref linkend="sql-rollback-to">.)
  46    Destroying a savepoint when
  47    it is no longer needed allows the system to reclaim some resources
  48    earlier than transaction end.
  49   </para>
  50
  51   <para>
  52    <command>RELEASE SAVEPOINT</command> also destroys all savepoints that were
  53    established after the named savepoint was established.
  54   </para>
  55  </refsect1>
  56
  57  <refsect1>
  58   <title>Parameters</title>
  59
  60   <variablelist>
  61    <varlistentry>
  62     <term><replaceable>savepoint_name</replaceable></term>
  63     <listitem>
  64      <para>
  65       The name of the savepoint to destroy.
  66      </para>
  67     </listitem>
  68    </varlistentry>
  69   </variablelist>
  70  </refsect1>
  71
  72  <refsect1>
  73   <title>Notes</title>
  74
  75   <para>
  76    Specifying a savepoint name that was not previously defined is an error.
  77   </para>
  78
  79   <para>
  80    It is not possible to release a savepoint when the transaction is in
  81    an aborted state.
  82   </para>
  83
  84   <para>
  85    If multiple savepoints have the same name, only the one that was most
  86    recently defined is released.
  87   </para>
  88
  89  </refsect1>
  90
  91  <refsect1>
  92   <title>Examples</title>
  93
  94   <para>
  95    To establish and later destroy a savepoint:
  96 <programlisting>
  97 BEGIN;
  98     INSERT INTO table1 VALUES (3);
  99     SAVEPOINT my_savepoint;
 100     INSERT INTO table1 VALUES (4);
 101     RELEASE SAVEPOINT my_savepoint;
 102 COMMIT;
 103 </programlisting>
 104    The above transaction will insert both 3 and 4.
 105   </para>
 106  </refsect1>
 107
 108  <refsect1>
 109   <title>Compatibility</title>
 110
 111   <para>
 112    This command conforms to the <acronym>SQL</> standard.  The standard
 113    specifies that the key word <literal>SAVEPOINT</literal> is
 114    mandatory, but <productname>PostgreSQL</productname> allows it to
 115    be omitted.
 116   </para>
 117  </refsect1>
 118
 119  <refsect1>
 120   <title>See Also</title>
 121
 122   <simplelist type="inline">
 123    <member><xref linkend="sql-begin"></member>
 124    <member><xref linkend="sql-commit"></member>
 125    <member><xref linkend="sql-rollback"></member>
 126    <member><xref linkend="sql-rollback-to"></member>
 127    <member><xref linkend="sql-savepoint"></member>
 128   </simplelist>
 129  </refsect1>
 130 </refentry>