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

<REFENTRY ID="SQL-BEGINWORK">
 <REFMETA>
  <REFENTRYTITLE>
   BEGIN WORK
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
   BEGIN WORK
  </REFNAME>
  <REFPURPOSE>
   Begins a transaction in chained mode
  </REFPURPOSE>
  
  </refnamediv>
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-08</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>  
BEGIN [ WORK | TRANSACTION ]
  </SYNOPSIS>
  
  <REFSECT2 ID="R2-SQL-BEGINWORK-1">
   <REFSECT2INFO>
    <DATE>1998-09-08</DATE>
   </REFSECT2INFO>
   <TITLE>
    Inputs
   </TITLE>
   <PARA>
    None
   </para>
  </REFSECT2>
  
  <REFSECT2 ID="R2-SQL-BEGINWORK-2">
   <REFSECT2INFO>
    <DATE>1998-09-08</DATE>
   </REFSECT2INFO>
   <TITLE>
    Outputs
   </TITLE>
   <PARA>

       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	  <returnvalue>BEGIN</returnvalue>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   This signifies that a new transaction has been started.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	   <returnvalue>NOTICE:  BeginTransactionBlock and not in default state</returnvalue>
	 </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>1998-09-08</DATE>
  </REFSECT1INFO>
  <TITLE>
   Description
  </TITLE>
  <para>
   By default, <productname>Postgres</productname> executes transactions
   in unchained mode (also known as autocommit feature in other DBMSes).
   In other words, each user statement is executed in its own transaction
   and commit is implicit (if execution was successfull).
   <command>BEGIN</command> initiates a user transaction in chained mode,
   i.e. all user statements after <command>BEGIN</command> command will
   be executed in single transaction untill explicit COMMIT, ROLLBACK
   or execution abort. Statements in chained mode are executed much faster, 
   because of transaction start/commit requires significant CPU and disk 
   activity. This mode is also required for consistency when changing 
   one of related tables.
  </para>
  <para>
   Default transaction isolation level in <productname>Postgres</productname>
   is READ COMMITTED one, when queries inside transaction see only changes
   committed before query execution. So, you have to use 
   <command>SET TRANSACTION ISOLATION LEVEL SERIALIZABLE</command>
   command just after BEGIN if you need in better transaction isolation. 
   In SERIALIZABLE mode queries will see only changes committed before entire
   transaction began (actually, before execution of first DML statement
   in 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 ACID
   (atomic, consistent, isolatable, and durable) property.
  </para>
  
  <REFSECT2 ID="R2-SQL-BEGINWORK-3">
   <REFSECT2INFO>
    <DATE>1998-09-08</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 <command>COMMIT</command> or <command>ROLLBACK</command>
    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>1998-09-08</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.
   </PARA>
   <PARA>
    <acronym>SQL92</acronym> also requires SERIALIZABLE to be default
    transaction isolation level.
   </PARA>
  </refsect2>
 </refsect1>
</REFENTRY>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
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:
-->