doc/src/sgml/ref/begin.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-BEGIN">
   7  <refmeta>
   8   <refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>BEGIN</refname>
  15   <refpurpose>start a transaction block</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-begin">
  19   <primary>BEGIN</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</replaceable> [, ...] ]
  25
  26 where <replaceable class="parameter">transaction_mode</replaceable> is one of:
  27
  28     ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
  29     READ WRITE | READ ONLY
  30 </synopsis>
  31  </refsynopsisdiv>
  32
  33  <refsect1>
  34   <title>Description</title>
  35
  36   <para>
  37    <command>BEGIN</command> initiates a transaction block, that is,
  38    all statements after a <command>BEGIN</command> command will be
  39    executed in a single transaction until an explicit <xref
  40    linkend="sql-commit" endterm="sql-commit-title"> or <xref
  41    linkend="sql-rollback" endterm="sql-rollback-title"> is given.
  42    By default (without <command>BEGIN</command>),
  43    <productname>PostgreSQL</productname> executes
  44    transactions in <quote>autocommit</quote> mode, that is, each
  45    statement is executed in its own transaction and a commit is
  46    implicitly performed at the end of the statement (if execution was
  47    successful, otherwise a rollback is done).
  48   </para>
  49
  50   <para>
  51    Statements are executed more quickly in a transaction block, because
  52    transaction start/commit requires significant CPU and disk
  53    activity. Execution of multiple statements inside a transaction is
  54    also useful to ensure consistency when making several related changes:
  55    other sessions will be unable to see the intermediate states
  56    wherein not all the related updates have been done.
  57   </para>
  58
  59   <para>
  60    If the isolation level or read/write mode is specified, the new
  61    transaction has those characteristics, as if
  62    <xref linkend="sql-set-transaction" endterm="sql-set-transaction-title">
  63    was executed.
  64   </para>
  65  </refsect1>
  66
  67  <refsect1>
  68   <title>Parameters</title>
  69
  70   <variablelist>
  71    <varlistentry>
  72     <term><literal>WORK</literal></term>
  73     <term><literal>TRANSACTION</literal></term>
  74     <listitem>
  75      <para>
  76       Optional key words. They have no effect.
  77      </para>
  78     </listitem>
  79    </varlistentry>
  80   </variablelist>
  81
  82   <para>
  83    Refer to <xref linkend="sql-set-transaction"
  84    endterm="sql-set-transaction-title"> for information on the meaning
  85    of the other parameters to this statement.
  86   </para>
  87  </refsect1>
  88
  89  <refsect1>
  90   <title>Notes</title>
  91
  92   <para>
  93    <xref linkend="sql-start-transaction"
  94    endterm="sql-start-transaction-title"> has the same functionality
  95    as <command>BEGIN</>.
  96   </para>
  97
  98   <para>
  99    Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> or
 100    <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
 101    to terminate a transaction block.
 102   </para>
 103
 104   <para>
 105    Issuing <command>BEGIN</> when already inside a transaction block will
 106    provoke a warning message.  The state of the transaction is not affected.
 107    To nest transactions within a transaction block, use savepoints
 108    (see <xref linkend="sql-savepoint" endterm="sql-savepoint-title">).
 109   </para>
 110
 111   <para>
 112    For reasons of backwards compatibility, the commas between successive
 113    <replaceable class="parameter">transaction_modes</replaceable> can be
 114    omitted.
 115   </para>
 116  </refsect1>
 117
 118  <refsect1>
 119   <title>Examples</title>
 120
 121   <para>
 122    To begin a transaction block:
 123
 124 <programlisting>
 125 BEGIN;
 126 </programlisting>
 127   </para>
 128  </refsect1>
 129
 130  <refsect1>
 131   <title>Compatibility</title>
 132
 133   <para>
 134    <command>BEGIN</command> is a <productname>PostgreSQL</productname>
 135    language extension.  It is equivalent to the SQL-standard command
 136    <xref linkend="sql-start-transaction"
 137    endterm="sql-start-transaction-title">, whose reference page
 138    contains additional compatibility information.
 139   </para>
 140
 141   <para>
 142    Incidentally, the <literal>BEGIN</literal> key word is used for a
 143    different purpose in embedded SQL. You are advised to be careful
 144    about the transaction semantics when porting database applications.
 145   </para>
 146  </refsect1>
 147
 148  <refsect1>
 149   <title>See Also</title>
 150
 151   <simplelist type="inline">
 152    <member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
 153    <member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
 154    <member><xref linkend="sql-start-transaction" endterm="sql-start-transaction-title"></member>
 155    <member><xref linkend="sql-savepoint" endterm="sql-savepoint-title"></member>
 156   </simplelist>
 157  </refsect1>
 158 </refentry>