<!--

$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.32 2004/08/08 01:48:31 momjian Exp $

$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.33 2004/08/12 21:00:21 tgl Exp $

PostgreSQL documentation

-->

<refsynopsisdiv>

<synopsis>

BEGIN [ WORK | TRANSACTION ]

[ ISOLATION LEVEL { READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SERIALIZABLE } ]

[ READ WRITE | READ ONLY ]

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>

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-start-transaction" endterm="sql-start-transaction-title">

for more information).

(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> may be

omitted.

</para>

</refsect1>

<para>

<command>BEGIN</command> is a <productname>PostgreSQL</productname>

language extension. There is no explicit <command>BEGIN</command>

command in the SQL standard; transaction initiation is

always implicit and it terminates either with a

<command>COMMIT</command> or <command>ROLLBACK</command> statement.

</para>

<para>

Other relational database systems may offer an autocommit feature

as a convenience.

language extension. It is equivalent to the SQL-standard command

<xref linkend="sql-start-transaction"

endterm="sql-start-transaction-title">, which see for additional

compatibility information.

</para>

<para>

<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.19 2003/11/29 19:51:39 pgsql Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.20 2004/08/12 21:00:22 tgl Exp $ -->

<refentry id="SQL-SET-TRANSACTION">

<refmeta>

<refentrytitle id="SQL-SET-TRANSACTION-TITLE">SET TRANSACTION</refentrytitle>

<refsynopsisdiv>

<synopsis>

SET TRANSACTION

[ ISOLATION LEVEL { READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SERIALIZABLE } ]

[ READ WRITE | READ ONLY ]

SET TRANSACTION <replaceable class="parameter">transaction_mode</replaceable> [, ...]

SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transaction_mode</replaceable> [, ...]

SET SESSION CHARACTERISTICS AS TRANSACTION

[ ISOLATION LEVEL { READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SERIALIZABLE } ]

[ READ WRITE | READ ONLY ]

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>

characteristics of the current transaction. It has no effect on any

subsequent transactions. <command>SET SESSION

CHARACTERISTICS</command> sets the default transaction

characteristics foreach transaction of a session. <command>SET

characteristics forsubsequent transactions of a session. <command>SET

TRANSACTION</command> can override it for an individual

transaction.

</para>

<para>

The isolation level of a transaction determines what data the

transaction can see when other transactions are running concurrently.

transaction can see when other transactions are running concurrently:

<variablelist>

<varlistentry>

<term><literal>SERIALIZABLE</literal></term>

<listitem>

<para>

The current transaction can only see rows committed before

first query or data-modification statement was executed in this transaction.

All statements of the current transaction can only see rows committed

before the first query or data-modification statement was executed in

this transaction.

</para>

<tip>

<para>

Intuitively, serializable means that two concurrent

transactions will leave the database in the same state as if

the twohas been executed strictly afterone anotherineither

order.

the twohad been executed strictlyoneafterthe other (inone

order or the other).

</para>

</tip>

</listitem>

</varlistentry>

</variablelist>

The level <literal>READ UNCOMMITTED</literal> is mapped to

<literal>READ COMMITTED</literal>, the level <literal>REPEATABLE

READ</literal> is mapped to <literal>SERIALIZABLE</literal>, The

transaction isolation level cannot be set after the first query or

The SQL standard defines two additional levels, <literal>READ

UNCOMMITTED</literal> and <literal>REPEATABLE READ</literal>.

In <productname>PostgreSQL</productname> <literal>READ

UNCOMMITTED</literal> is treated as

<literal>READ COMMITTED</literal>, while <literal>REPEATABLE

READ</literal> is treated as <literal>SERIALIZABLE</literal>.

</para>

<para>

The transaction isolation level cannot be changed after the first query or

data-modification statement (<command>SELECT</command>,

<command>INSERT</command>, <command>DELETE</command>,

<command>UPDATE</command>, <command>FETCH</command>,

<command>UPDATE</command>, <command>FETCH</command>, or

<command>COPY</command>) of a transaction has been executed. See

<xref linkend="mvcc"> for more information about transaction

isolation and concurrency control.

<title>Notes</title>

<para>

The session default transaction isolation level can also be set

with the command

<programlisting>

SET default_transaction_isolation = '<replaceable>value</replaceable>'

</programlisting>

and in the configuration file. Consult <xref linkend="runtime-config"> for more

information.

If <command>SET TRANSACTION</command> is executed without a prior

<command>START TRANSACTION</command> or <command>BEGIN</command>,

it will appear to have no effect, since the transaction will immediately

end.

</para>

<para>

It is possible to dispense with <command>SET TRANSACTION</command> by

instead specifying the desired <replaceable

class="parameter">transaction_modes</replaceable> in

<command>START TRANSACTION</command>.

</para>

<para>

The session default transaction modes can also be set by setting the

configuration parameters <xref linkend="guc-default-transaction-isolation">

and <xref linkend="guc-default-transaction-read-only">.

(In fact <command>SET SESSION CHARACTERISTICS</command> is just a

verbose equivalent for setting these variables with <command>SET</>.)

This allows them to be set in the configuration file. Consult <xref

linkend="runtime-config"> for more information.

</para>

</refsect1>

isolation level in the standard; in

<productname>PostgreSQL</productname> the default is ordinarily

<literal>READ COMMITTED</literal>, but you can change it as

described above. Because of multiversion concurrency control, the

mentioned above. Because of multiversion concurrency control, the

<literal>SERIALIZABLE</literal> level is not truly

serializable. See <xref linkend="mvcc"> for details.

</para>

<para>

In the SQL standard, there is one other transaction characteristic

that can be set with these commands: the size of the diagnostics

area. This concept is only for use in embedded SQL.

area. This concept is specific to embedded SQL, and therefore is

not implemented in the <productname>PostgreSQL</productname> server.

</para>

<para>

The SQL standard requires commas between successive <replaceable

class="parameter">transaction_modes</replaceable>, but for historical

reasons <productname>PostgreSQL</productname> allows the commas to be

omitted.

</para>

</refsect1>

</refentry>

<!--

$PostgreSQL: pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.12 2004/08/01 17:32:13 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.13 2004/08/12 21:00:23 tgl Exp $

PostgreSQL documentation

-->

<refsynopsisdiv>

<synopsis>

START TRANSACTION

[ ISOLATION LEVEL { READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SERIALIZABLE } ]

[ READ WRITE | READ ONLY ]

START 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>

This command begins a new transaction. If the isolation level or

This command begins a new transaction block. 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.It is the same

endterm="sql-set-transaction-title"> was executed.This is the same

as the <xref linkend="sql-begin" endterm="sql-begin-title"> command.

</para>

</refsect1>

<title>Compatibility</title>

<para>

This command conforms to the SQL standard; but see also the

compatibility section of <xref linkend="sql-set-transaction"

In the standard, it is not necessary to issue <command>START TRANSACTION</>

to start a transaction block: any SQL command implicitly begins a block.

<productname>PostgreSQL</productname>'s behavior can be seen as implicitly

issuing a <command>COMMIT</command> after each command that does not

follow <command>START TRANSACTION</> (or <command>BEGIN</command>),

and it is therefore often called <quote>autocommit</>.

Other relational database systems may offer an autocommit feature

as a convenience.

</para>

<para>

The SQL standard requires commas between successive <replaceable

class="parameter">transaction_modes</replaceable>, but for historical

reasons <productname>PostgreSQL</productname> allows the commas to be

omitted.

</para>

<para>

See also the compatibility section of <xref linkend="sql-set-transaction"

endterm="sql-set-transaction-title">.

</para>

</refsect1>

|/*EMPTY*/{}

;

transaction_mode_list:

transaction_mode_item:

ISOLATION LEVEL iso_level

{$$ = list_make1(makeDefElem("transaction_isolation",

makeStringConst($3,NULL))); }

| transaction_access_mode

{$$ = list_make1(makeDefElem("transaction_read_only",

makeIntConst($1))); }

| ISOLATION LEVEL iso_level transaction_access_mode

{

$$ = list_make2(makeDefElem("transaction_isolation",

makeStringConst($3,NULL)),

makeDefElem("transaction_read_only",

makeIntConst($4)));

}

| transaction_access_mode ISOLATION LEVEL iso_level

{

$$ =list_make2(makeDefElem("transaction_read_only",

makeIntConst($1)),

makeDefElem("transaction_isolation",

makeStringConst($4,NULL)));

}

{$$ = makeDefElem("transaction_isolation",

makeStringConst($3,NULL)); }

| READ ONLY

{$$ = makeDefElem("transaction_read_only",

makeIntConst(TRUE)); }

| READ WRITE

{$$ = makeDefElem("transaction_read_only",

makeIntConst(FALSE)); }

;

transaction_mode_list:

transaction_mode_item

{$$ = list_make1($1); }

| transaction_mode_list',' transaction_mode_item

{$$ = lappend($1,$3); }

| transaction_mode_list transaction_mode_item

{$$ = lappend($1,$2); }

;

transaction_mode_list_or_empty:

{$$ = NIL; }

;

transaction_access_mode:

READ ONLY { $$ =TRUE; }

| READ WRITE { $$ =FALSE; }

;