| <!-- |
| $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"> |
| <refmeta> |
| <refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle> |
| <manvolnum>7</manvolnum> |
| <refmiscinfo>SQL - Language Statements</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>BEGIN</refname> |
| <refpurpose>start a transaction block</refpurpose> |
| </refnamediv> |
| |
| <indexterm zone="sql-begin"> |
| <primary>BEGIN</primary> |
| </indexterm> |
| |
| <refsynopsisdiv> |
| <synopsis> |
| BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</replaceable> [, ...] ] |
| |
| where <replaceable class="parameter">transaction_mode</replaceable> is one of: |
| |
| ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } |
| READ WRITE | READ ONLY |
| </synopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para> |
| <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). |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Parameters</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><literal>WORK</literal></term> |
| <term><literal>TRANSACTION</literal></term> |
| <listitem> |
| <para> |
| Optional key words. They have no effect. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para> |
| Refer to <xref linkend="sql-set-transaction" |
| endterm="sql-set-transaction-title"> for information on the meaning |
| of the other parameters to this statement. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Notes</title> |
| |
| <para> |
| <xref linkend="sql-start-transaction" |
| endterm="sql-start-transaction-title"> has the same functionality |
| as <command>BEGIN</>. |
| </para> |
| |
| <para> |
| Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> or |
| <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> |
| to terminate a transaction block. |
| </para> |
| |
| <para> |
| 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">). |
| </para> |
| |
| <para> |
| For reasons of backwards compatibility, the commas between successive |
| <replaceable class="parameter">transaction_modes</replaceable> can be |
| omitted. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| |
| <para> |
| To begin a transaction block: |
| |
| <programlisting> |
| BEGIN; |
| </programlisting> |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Compatibility</title> |
| |
| <para> |
| <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. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <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> |
| </simplelist> |
| </refsect1> |
| </refentry> |