aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/ref/begin.sgml33
-rw-r--r--doc/src/sgml/ref/set_transaction.sgml83
-rw-r--r--doc/src/sgml/ref/start_transaction.sgml36
3 files changed, 102 insertions, 50 deletions
diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml
index bf1195f5277..741d8aa997a 100644
--- a/doc/src/sgml/ref/begin.sgml
+++ b/doc/src/sgml/ref/begin.sgml
@@ -1,5 +1,5 @@
<!--
-$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
-->
@@ -20,9 +20,12 @@ 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>
@@ -101,8 +104,13 @@ BEGIN [ WORK | TRANSACTION ]
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>
@@ -123,15 +131,10 @@ BEGIN;
<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>
diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml
index ef6dea1ac18..50a89088250 100644
--- a/doc/src/sgml/ref/set_transaction.sgml
+++ b/doc/src/sgml/ref/set_transaction.sgml
@@ -1,4 +1,4 @@
-<!-- $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>
@@ -16,13 +16,13 @@
<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>
@@ -34,7 +34,7 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
characteristics of the current transaction. It has no effect on any
subsequent transactions. <command>SET SESSION
CHARACTERISTICS</command> sets the default transaction
- characteristics for each transaction of a session. <command>SET
+ characteristics for subsequent transactions of a session. <command>SET
TRANSACTION</command> can override it for an individual
transaction.
</para>
@@ -47,7 +47,7 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
<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>
@@ -64,28 +64,35 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
<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 two has been executed strictly after one another in either
- order.
+ the two had been executed strictly one after the other (in one
+ 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.
@@ -112,13 +119,27 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
<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>
@@ -131,7 +152,7 @@ SET default_transaction_isolation = '<replaceable>value</replaceable>'
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>
@@ -139,7 +160,15 @@ SET default_transaction_isolation = '<replaceable>value</replaceable>'
<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>
diff --git a/doc/src/sgml/ref/start_transaction.sgml b/doc/src/sgml/ref/start_transaction.sgml
index 1a7bc363ce7..823bd991953 100644
--- a/doc/src/sgml/ref/start_transaction.sgml
+++ b/doc/src/sgml/ref/start_transaction.sgml
@@ -1,5 +1,5 @@
<!--
-$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
-->
@@ -20,9 +20,12 @@ 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>
@@ -30,10 +33,10 @@ START TRANSACTION
<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>
@@ -52,8 +55,25 @@ START TRANSACTION
<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>