doc/src/sgml/ref/release_savepoint.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/release_savepoint.sgml,v 1.6 2006/09/16 00:30:19 momjian Exp $
PostgreSQL documentation
-->

<refentry id="SQL-RELEASE-SAVEPOINT">
 <refmeta>
  <refentrytitle id="SQL-RELEASE-SAVEPOINT-TITLE">RELEASE SAVEPOINT</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

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

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

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

 <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"
   endterm="sql-rollback-to-title">.)  Destroying a savepoint when
   it is no longer needed may allow 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 one that was most
   recently defined is released.
  </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</> 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" endterm="sql-begin-title"></member>
   <member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
   <member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
   <member><xref linkend="sql-rollback-to" endterm="sql-rollback-to-title"></member>
   <member><xref linkend="sql-savepoint" endterm="sql-savepoint-title"></member>
  </simplelist>
 </refsect1>
</refentry>