doc/src/sgml/ref/release_savepoint.sgml

<!--
doc/src/sgml/ref/release_savepoint.sgml
PostgreSQL documentation
-->

<refentry id="sql-release-savepoint">
 <indexterm zone="sql-release-savepoint">
  <primary>RELEASE SAVEPOINT</primary>
 </indexterm>

 <indexterm zone="sql-release-savepoint">
  <primary>savepoints</primary>
  <secondary>releasing</secondary>
 </indexterm>

 <refmeta>
  <refentrytitle>RELEASE SAVEPOINT</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>RELEASE SAVEPOINT</refname>
  <refpurpose>destroy a previously defined savepoint</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <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.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable>savepoint_name</replaceable></term>
    <listitem>
     <para>
      The name of the savepoint to destroy.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Specifying a savepoint name that was not previously defined is an error.
  </para>

  <para>
   It is not possible to release a savepoint when the transaction is in
   an aborted state.
  </para>

  <para>
   If multiple savepoints have the same name, only the most recently defined
   unreleased one is released.  Repeated commands will release progressively
   older savepoints.
  </para>

 </refsect1>

 <refsect1>
  <title>Examples</title>

  <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>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   This command conforms to the <acronym>SQL</acronym> standard.  The standard
   specifies that the key word <literal>SAVEPOINT</literal> is
   mandatory, but <productname>PostgreSQL</productname> allows it to
   be omitted.
  </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-rollback"/></member>
   <member><xref linkend="sql-rollback-to"/></member>
   <member><xref linkend="sql-savepoint"/></member>
  </simplelist>
 </refsect1>
</refentry>