blob: 3dd5df9827bcbfd5d88d77ea82a5e94ccf284a2f [file] [log] [blame]
$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.37 2008/11/14 10:22:45 petere Exp $
PostgreSQL documentation
<refentry id="SQL-BEGIN">
<refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
<refpurpose>start a transaction block</refpurpose>
<indexterm zone="sql-begin">
BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</replaceable> [, ...] ]
where <replaceable class="parameter">transaction_mode</replaceable> is one of:
<command>BEGIN</command> initiates a transaction block, that is,
all statements after a <command>BEGIN</command> command will be
executed in a single transaction until an explicit <xref
linkend="sql-commit" endterm="sql-commit-title"> or <xref
linkend="sql-rollback" endterm="sql-rollback-title"> is given.
By default (without <command>BEGIN</command>),
<productname>PostgreSQL</productname> executes
transactions in <quote>autocommit</quote> mode, that is, each
statement is executed in its own transaction and a commit is
implicitly performed at the end of the statement (if execution was
successful, otherwise a rollback is done).
Statements are executed more quickly in a transaction block, because
transaction start/commit requires significant CPU and disk
activity. Execution of multiple statements inside a transaction is
also useful to ensure consistency when making several related changes:
other sessions will be unable to see the intermediate states
wherein not all the related updates have been done.
If the isolation level or read/write mode is specified, the new
transaction has those characteristics, as if
<xref linkend="sql-set-transaction" endterm="sql-set-transaction-title">
was executed.
Optional key words. They have no effect.
Refer to <xref linkend="sql-set-transaction"
endterm="sql-set-transaction-title"> for information on the meaning
of the other parameters to this statement.
<xref linkend="sql-start-transaction"
endterm="sql-start-transaction-title"> has the same functionality
as <command>BEGIN</>.
Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> or
<xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
to terminate a transaction block.
Issuing <command>BEGIN</> when already inside a transaction block will
provoke a warning message. The state of the transaction is not affected.
To nest transactions within a transaction block, use savepoints
(see <xref linkend="sql-savepoint" endterm="sql-savepoint-title">).
For reasons of backwards compatibility, the commas between successive
<replaceable class="parameter">transaction_modes</replaceable> can be
To begin a transaction block:
<command>BEGIN</command> is a <productname>PostgreSQL</productname>
language extension. It is equivalent to the SQL-standard command
<xref linkend="sql-start-transaction"
endterm="sql-start-transaction-title">, whose reference page
contains additional compatibility information.
Incidentally, the <literal>BEGIN</literal> key word is used for a
different purpose in embedded SQL. You are advised to be careful
about the transaction semantics when porting database applications.
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
<member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
<member><xref linkend="sql-start-transaction" endterm="sql-start-transaction-title"></member>
<member><xref linkend="sql-savepoint" endterm="sql-savepoint-title"></member>