← Back to branch summary

~ubuntu-branches/debian/sid/postgresql-9.3/sid

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/begin.sgml

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2013-05-08 05:39:52 UTC
  • Revision ID: package-import@ubuntu.com-20130508053952-1j7uilp7mjtrvq8q
Tags: upstream-9.3~beta1
Import upstream version 9.3~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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>