From 9c279355fbf332dbf6dcebbe10d38e10503bf4dd Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 30 Aug 2002 22:45:25 +0000
Subject: [PATCH] Updates to reflect availability of autocommit option.

---
 doc/src/sgml/ref/begin.sgml             | 47 +++++++++++++++++++++------------
 doc/src/sgml/ref/start_transaction.sgml | 23 ++++++++++------
 2 files changed, 45 insertions(+), 25 deletions(-)

diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml
index 850bfd77e6..11ca82e6d4 100644
--- a/doc/src/sgml/ref/begin.sgml
+++ b/doc/src/sgml/ref/begin.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.18 2002/08/04 04:31:44 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.19 2002/08/30 22:45:25 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -103,33 +103,35 @@ WARNING:  BEGIN: already a transaction in progress
    <command>BEGIN</command> initiates a user transaction in chained mode,
    i.e., all user statements after <command>BEGIN</command> command will
    be executed in a single transaction until an explicit 
-   <xref linkend="sql-commit" endterm="sql-commit-title">,
-   <xref linkend="sql-rollback" endterm="sql-rollback-title">,
-   or execution abort. Statements in chained mode are executed much faster, 
+   <xref linkend="sql-commit" endterm="sql-commit-title"> or
+   <xref linkend="sql-rollback" endterm="sql-rollback-title">.
+   Statements are executed more quickly in chained mode,
    because transaction start/commit requires significant CPU and disk 
    activity. Execution of multiple statements inside a transaction
-   is also required for consistency when changing several
-   related tables.
+   is also useful to ensure consistency when changing several
+   related tables: other clients will be unable to see the intermediate
+   states wherein not all the related updates have been done.
   </para>
 
   <para>
    The default transaction isolation level in
    <productname>PostgreSQL</productname>
-   is READ COMMITTED, where queries inside the transaction see only changes
-   committed before query execution. So, you have to use 
+   is READ COMMITTED, wherein each query inside the transaction sees changes
+   committed before that query begins execution. So, you have to use 
    <command>SET TRANSACTION ISOLATION LEVEL SERIALIZABLE</command>
-   just after <command>BEGIN</command> if you need more rigorous transaction isolation. 
+   just after <command>BEGIN</command> if you need more rigorous transaction
+   isolation.  (Alternatively, you can change the default transaction
+   isolation level; see the <citetitle>PostgreSQL Administrator's
+   Guide</citetitle> for details.)
    In SERIALIZABLE mode queries will see only changes committed before
    the entire
    transaction began (actually, before execution of the first DML statement
-   in a serializable transaction).
+   in the transaction).
   </para>
 
   <para>
-   If the transaction is committed, <productname>PostgreSQL</productname> 
-   will ensure either that all updates are done or else that none of
-   them are done. Transactions have the standard <acronym>ACID</acronym>
-   (atomic, consistent, isolatable, and durable) property.
+   Transactions have the standard <acronym>ACID</acronym>
+   (atomic, consistent, isolatable, and durable) properties.
   </para>
   
   <refsect2 id="R2-SQL-BEGIN-3">
@@ -140,9 +142,9 @@ WARNING:  BEGIN: already a transaction in progress
     Notes
    </title>
    <para>
-    Refer to <xref linkend="sql-lock" endterm="sql-lock-title">
-    for further information
-    about locking tables inside a transaction.
+    <xref linkend="sql-start-transaction"
+    endterm="sql-start-transaction-title"> has the same functionality
+    as <command>BEGIN</>.
    </para>
    
    <para>
@@ -151,6 +153,17 @@ WARNING:  BEGIN: already a transaction in progress
     <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
     to terminate a transaction.
    </para>
+
+   <para>
+    Refer to <xref linkend="sql-lock" endterm="sql-lock-title">
+    for further information
+    about locking tables inside a transaction.
+   </para>
+   
+   <para>
+    If you turn <literal>autocommit</> mode off, then <command>BEGIN</>
+    is not required: any SQL command automatically starts a transaction.
+   </para>
   </refsect2>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/start_transaction.sgml b/doc/src/sgml/ref/start_transaction.sgml
index 2e657c610b..fb8dd13193 100644
--- a/doc/src/sgml/ref/start_transaction.sgml
+++ b/doc/src/sgml/ref/start_transaction.sgml
@@ -1,4 +1,8 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.2 2002/08/06 05:32:16 momjian Exp $ -->
+<!--
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.3 2002/08/30 22:45:25 tgl Exp $
+PostgreSQL documentation
+-->
+
 <refentry id="SQL-START-TRANSACTION">
  <docinfo>
   <date>2002-07-26</date>
@@ -76,7 +80,7 @@ WARNING:  BEGIN: already a transaction in progress
    This command begins a new transaction. If the isolation level is
    specified, the new transaction has that isolation level. In all other
    respects, the behavior of this command is identical to the
-   <command>BEGIN</command> command.
+   <xref linkend="sql-begin" endterm="sql-begin-title"> command.
   </para>
 
  </refsect1>
@@ -87,8 +91,8 @@ WARNING:  BEGIN: already a transaction in progress
   <para>
    The isolation level of a transaction can also be set with the <xref
    linkend="sql-set-transaction" endterm="sql-set-transaction-title">
-   command. If no isolation level is specified, the level defaults to
-   <option>READ COMMITTED</option>.
+   command. If no isolation level is specified, the default isolation
+   level is used.
   </para>
  </refsect1>
 
@@ -99,11 +103,14 @@ WARNING:  BEGIN: already a transaction in progress
    <title>SQL99</title>
 
    <para>
-    <option>SERIALIZABLE</option> is the default level in
-    <acronym>SQL</acronym>. <productname>PostgreSQL</productname>
+    <option>SERIALIZABLE</option> is the default isolation level in
+    <acronym>SQL99</acronym>, but it is not the usual default in
+    <productname>PostgreSQL</productname>: the factory default setting
+    is READ COMMITTED.
+    <productname>PostgreSQL</productname> 
     does not provide the isolation levels <option>READ UNCOMMITTED</option>
-    and <option>REPEATABLE READ</option>. Because of multiversion
-    concurrency control, the <option>SERIALIZABLE</option> level is
+    and <option>REPEATABLE READ</option>. Because of lack of predicate
+    locking, the <option>SERIALIZABLE</option> level is
     not truly serializable. See the <citetitle>User's Guide</citetitle>
     for details.
    </para>
-- 
2.11.0