Debian Codegraph @

doc/src/sgml/ref/begin.sgml

raw
1 <!--
2 doc/src/sgml/ref/begin.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-begin">
7 <indexterm zone="sql-begin">
8 <primary>BEGIN</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle>BEGIN</refentrytitle>
13 <manvolnum>7</manvolnum>
14 <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>BEGIN</refname>
19 <refpurpose>start a transaction block</refpurpose>
20 </refnamediv>
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 <link
41 linkend="sql-commit"><command>COMMIT</command></link> or <link
42 linkend="sql-rollback"><command>ROLLBACK</command></link> 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 <link linkend="sql-set-transaction"><command>SET TRANSACTION</command></link>
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 <link linkend="sql-start-transaction"><command>START TRANSACTION</command></link> has the same functionality
94 as <command>BEGIN</command>.
95 </para>
96
97 <para>
98 Use <link linkend="sql-commit"><command>COMMIT</command></link> or
99 <link linkend="sql-rollback"><command>ROLLBACK</command></link>
100 to terminate a transaction block.
101 </para>
102
103 <para>
104 Issuing <command>BEGIN</command> 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 <link linkend="sql-start-transaction"><command>START TRANSACTION</command></link>, 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>