postgres/doc/src/sgml/ref/begin.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.14 2001/09/03 12:57:49 petere Exp $
Postgres documentation
-->

<refentry id="SQL-BEGIN">
 <refmeta>
  <refentrytitle id="SQL-BEGIN-TITLE">
   BEGIN
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   BEGIN
  </refname>
  <refpurpose>
   start a transaction block
  </refpurpose>
  
  </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>  
BEGIN [ WORK | TRANSACTION ]
  </synopsis>
  
  <refsect2 id="R2-SQL-BEGIN-1">
   <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term>WORK</term>
      <term>TRANSACTION</term>
      <listitem>
       <para>
	Optional keywords. They have no effect.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
  
  <refsect2 id="R2-SQL-BEGIN-2">
   <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    Outputs
   </title>

   <para>
    <variablelist>
     <varlistentry>
      <term><computeroutput>
BEGIN
       </computeroutput></term>
      <listitem>
       <para>
	This signifies that a new transaction has been started.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
NOTICE:  BEGIN: already a transaction in progress
       </computeroutput></term>
      <listitem>
       <para>
	This indicates that a transaction was already in progress.
	The current transaction is not affected.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>
 
 <refsect1 id="R1-SQL-BEGIN-1">
  <refsect1info>
   <date>1999-06-11</date>
  </refsect1info>
  <title>
   Description
  </title>

  <para>
   By default, <productname>Postgres</productname> executes transactions
   in <firstterm>unchained mode</firstterm>
   (also known as <quote>autocommit</quote> in other database
   systems).
   In other words, each user statement is executed in its own transaction
   and a commit is implicitly performed at the end of the statement
   (if execution was successful, otherwise a rollback is done).
   <command>BEGIN</command> initiates a user transaction in chained mode,
   i.e., all user statements after <command>BEGIN</command> command will
   be executed in a single transaction until an explicit 
   <xref linkend="sql-commit" endterm="sql-commit-title">,
   <xref linkend="sql-rollback" endterm="sql-rollback-title">,
   or execution abort. Statements in chained mode are executed much faster, 
   because transaction start/commit requires significant CPU and disk 
   activity. Execution of multiple statements inside a transaction
   is also required for consistency when changing several
   related tables.
  </para>

  <para>
   The default transaction isolation level in
   <productname>Postgres</productname>
   is READ COMMITTED, where queries inside the transaction see only changes
   committed before query execution. So, you have to use 
   <command>SET TRANSACTION ISOLATION LEVEL SERIALIZABLE</command>
   just after <command>BEGIN</command> if you need more rigorous transaction isolation. 
   In SERIALIZABLE mode queries will see only changes committed before
   the entire
   transaction began (actually, before execution of the first DML statement
   in a serializable transaction).
  </para>

  <para>
   If the transaction is committed, <productname>Postgres</productname> 
   will ensure either that all updates are done or else that none of
   them are done. Transactions have the standard <acronym>ACID</acronym>
   (atomic, consistent, isolatable, and durable) property.
  </para>
  
  <refsect2 id="R2-SQL-BEGIN-3">
   <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    Refer to <xref linkend="sql-lock" endterm="sql-lock-title">
    for further information
    about locking tables inside a transaction.
   </para>
   
   <para>
    Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE">
    or
    <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
    to terminate a transaction.
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-BEGIN-2">
  <title>
   Usage
  </title>

  <para>
   To begin a user transaction:

  <programlisting>
BEGIN WORK;
  </programlisting>
  </para>
 </refsect1>
 
 <refsect1 id="R1-SQL-BEGIN-3">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-BEGIN-4">
     <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    SQL92
   </title>

   <para>
    <command>BEGIN</command>
    is a <productname>Postgres</productname> language extension.
    There is no explicit <command>BEGIN</command>
    command in <acronym>SQL92</acronym>;
    transaction initiation is always implicit and it terminates either 
    with a <command>COMMIT</command> or <command>ROLLBACK</command> statement.

    <note>
     <para>
      Many relational database systems offer an autocommit feature as a
      convenience.
     </para>
    </note>
   </para>

   <para>
    Incidentally, the <literal>BEGIN</literal> keyword is used for a different
    purpose in embedded SQL. You are advised to be careful about the transaction
    semantics when porting database applications.
   </para>

   <para>
    <acronym>SQL92</acronym> also requires SERIALIZABLE to be the default
    transaction isolation level.
   </para>
  </refsect2>
 </refsect1>
</refentry>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->