granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/begin.sgml

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