postgresql/doc/src/sgml/ref/begin.sgml

<refentry id="SQL-BEGINWORK">
 <refmeta>
  <refentrytitle id="SQL-BEGINWORK-TITLE">
   BEGIN
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   BEGIN
  </refname>
  <refpurpose>
   Begins a transaction in chained mode
  </refpurpose>
  
  </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-06-11</date>
  </refsynopsisdivinfo>
  <synopsis>  
BEGIN [ WORK | TRANSACTION ]
  </synopsis>
  
  <refsect2 id="R2-SQL-BEGINWORK-1">
   <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
    None.
   </para>
  </refsect2>
  
  <refsect2 id="R2-SQL-BEGINWORK-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:  BeginTransactionBlock and not in default state
       </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-BEGINWORK-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 COMMIT, ROLLBACK
   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 BEGIN 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-BEGINWORK-3">
   <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    The keyword TRANSACTION is just a cosmetic alternative to WORK.
    Neither keyword need be specified.
   </para>

   <para>
    Refer to the <command>LOCK</command> statement for further information
    about locking tables inside a transaction.
   </para>
   
   <para>
    Use <xref linkend="SQL-COMMIT-TITLE" endterm="SQL-COMMIT-TITLE">
    or
    <xref linkend="SQL-ROLLBACK-TITLE" endterm="SQL-ROLLBACK-TITLE">
    to terminate a transaction.
   </para>
  </refsect2>
 </refsect1>

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

  <para>
   To begin a user transaction:

  <programlisting>
BEGIN WORK;
  </programlisting>
  </para>
 </refsect1>
 
 <refsect1 id="R1-SQL-BEGINWORK-3">
  <title>
   Compatibility
  </title>
  <para>
    <command>BEGIN</command>
    is a <productname>Postgres</productname> language extension.
  </para>
  <refsect2 id="R2-SQL-BEGINWORK-4">
     <refsect2info>
    <date>1999-06-11</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para> 
    There is no explicit BEGIN WORK command in <acronym>SQL92</acronym>;
    transaction initiation is always implicit and it terminates either 
    with a COMMIT or with a ROLLBACK statement.

    <note>
     <para>
      Many relational database systems offer an autocommit feature as a
      convenience.
     </para>
    </note>
   </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:
-->