Read-only transactions, as defined in SQL.

4 files changed, 75 insertions, 79 deletions

diff --git a/doc/src/sgml/features.sgml b/doc/src/sgml/features.sgml
index fd01cd3cce6..9c7cc471935 100644
--- a/doc/src/sgml/features.sgml
+++ b/doc/src/sgml/features.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.13 2003/01/10 11:02:41 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.14 2003/01/10 22:03:26 petere Exp $
 -->
 
 <appendix id="features">
@@ -643,6 +643,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.13 2003/01/10 11:02:41 pe
         <entry></entry>
        </row>
        <row>
+        <entry>E152</entry>
+        <entry>Core</entry>
+        <entry>Basic SET TRANSACTION statement</entry>
+        <entry></entry>
+       </row>
+       <row>
         <entry>E152-01</entry>
         <entry>Core</entry>
         <entry>SET TRANSACTION statement: ISOLATION LEVEL SERIALIZABLE
@@ -650,6 +656,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.13 2003/01/10 11:02:41 pe
         <entry></entry>
        </row>
        <row>
+        <entry>E152-02</entry>
+        <entry>Core</entry>
+        <entry>SET TRANSACTION statement: READ ONLY and READ WRITE
+         clauses</entry> 
+        <entry></entry>
+       </row>
+       <row>
         <entry>E161</entry>
         <entry>Core</entry>
         <entry>SQL comments using leading double minus</entry>
@@ -1599,19 +1612,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/features.sgml,v 2.13 2003/01/10 11:02:41 pe
         <entry>Cursor to stay open across transactions</entry>
        </row>
        <row>
-        <entry>E152</entry>
-        <entry>Core</entry>
-        <entry>Basic SET TRANSACTION statement</entry>
-        <entry></entry>
-       </row>
-       <row>
-        <entry>E152-02</entry>
-        <entry>Core</entry>
-        <entry>SET TRANSACTION statement: READ ONLY and READ WRITE
-         clauses</entry> 
-        <entry>Syntax accepted; READ ONLY not supported</entry>
-       </row>
-       <row>
         <entry>E153</entry>
         <entry>Core</entry>
         <entry>Updatable queries with subqueries</entry>
diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml
index 315a999330f..f39e0eb7fe6 100644
--- a/doc/src/sgml/ref/set_transaction.sgml
+++ b/doc/src/sgml/ref/set_transaction.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.9 2002/08/04 04:31:44 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.10 2003/01/10 22:03:27 petere Exp $ -->
 <refentry id="SQL-SET-TRANSACTION">
  <docinfo>
   <date>2000-11-24</date>
@@ -16,9 +16,10 @@
 
  <refsynopsisdiv>
   <synopsis>
-SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
-SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
-    { READ COMMITTED | SERIALIZABLE }
+SET TRANSACTION
+    [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
+SET SESSION CHARACTERISTICS AS TRANSACTION
+    [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
   </synopsis>
  </refsynopsisdiv>
 
@@ -26,17 +27,19 @@ SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
   <title>Description</title>
 
   <para>
-   This command sets the transaction isolation level.  The
-   <command>SET TRANSACTION</command> command sets the characteristics
-   for the current SQL-transaction. It has no effect on any subsequent
-   transactions.  This command cannot be used after the first query or data-modification
-   statement (<command>SELECT</command>, <command>INSERT</command>,
-   <command>DELETE</command>, <command>UPDATE</command>,
-   <command>FETCH</command>, <command>COPY</command>) of a transaction
-   has been executed.  <command>SET SESSION CHARACTERISTICS</command>
-   sets the default transaction isolation level for each transaction
-   for a session.  <command>SET TRANSACTION</command> can override it
-   for an individual transaction.
+   The <command>SET TRANSACTION</command> command sets the transaction
+   characteristics of the current SQL-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
+   TRANSACTION</command> can override it for an individual
+   transaction.
+  </para>
+
+  <para>
+   The available transaction characteristics are the transaction
+   isolation level and the transaction access mode (read/write or
+   read-only).
   </para>
 
   <para>
@@ -45,7 +48,7 @@ SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
 
    <variablelist>
     <varlistentry>
-     <term>READ COMMITTED</term>
+     <term><literal>READ COMMITTED<literal></term>
      <listitem>
       <para>
        A statement can only see rows committed before it began. This
@@ -55,7 +58,7 @@ SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
     </varlistentry>
 
     <varlistentry>
-     <term>SERIALIZABLE</term>
+     <term><literal>SERIALIZABLE</literal></term>
      <listitem>
       <para>
        The current transaction can only see rows committed before
@@ -72,6 +75,28 @@ SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
      </listitem>
     </varlistentry>
    </variablelist>
+
+   The transaction isolation level cannot be set after the first query
+   or data-modification statement (<command>SELECT</command>,
+   <command>INSERT</command>, <command>DELETE</command>,
+   <command>UPDATE</command>, <command>FETCH</command>,
+   <command>COPY</command>) of a transaction has been executed.
+  </para>
+
+  <para>
+   The transaction access mode determines whether the transaction is
+   read/write or read-only.  Read/write is the default.  When a
+   transaction is read-only, the following SQL commands are
+   disallowed: <literal>INSERT</literal>, <literal>UPDATE</literal>,
+   <literal>DELETE</literal>, and <literal>COPY TO</literal> if the
+   table they would write to is not a temporary table; all
+   <literal>CREATE</literal>, <literal>ALTER</literal>, and
+   <literal>DROP</literal> commands; <literal>COMMENT</literal>,
+   <literal>GRANT</literal>, <literal>REVOKE</literal>,
+   <literal>TRUNCATE</literal>; and <literal>EXPLAIN ANALYZE</literal>
+   and <literal>EXECUTE</literal> if the command they would execute is
+   among those listed.  This is a high-level notion of read-only that
+   does not prevent writes to disk.
   </para>
  </refsect1>
 
@@ -97,7 +122,7 @@ SET default_transaction_isolation = '<replaceable>value</replaceable>'
    <title>SQL92, SQL99</title>
 
    <para>
-    <option>SERIALIZABLE</option> is the default level in
+    <option>SERIALIZABLE</option> is the default transaction isolation level in
     <acronym>SQL</acronym>.  <productname>PostgreSQL</productname> does
     not provide the isolation levels <option>READ UNCOMMITTED</option> 
     and <option>REPEATABLE READ</option>. Because of multiversion
@@ -107,11 +132,10 @@ SET default_transaction_isolation = '<replaceable>value</replaceable>'
    </para>
 
    <para>
-    In <acronym>SQL</acronym> there are two other transaction
-    characteristics that can be set with these commands: whether the
-    transaction is read-only and the size of the diagnostics area.
-    Neither of these concepts are supported in
-    <productname>PostgreSQL</productname>. 
+    In <acronym>SQL</acronym> there is one other transaction
+    characteristic that can be set with these commands: the size of
+    the diagnostics area.  This concept is not supported in
+    <productname>PostgreSQL</productname>.
    </para>
   </refsect2>
  </refsect1>
diff --git a/doc/src/sgml/ref/start_transaction.sgml b/doc/src/sgml/ref/start_transaction.sgml
index fb8dd131932..087a0df1774 100644
--- a/doc/src/sgml/ref/start_transaction.sgml
+++ b/doc/src/sgml/ref/start_transaction.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.3 2002/08/30 22:45:25 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.4 2003/01/10 22:03:27 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
   <synopsis>
-START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ]
+START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
   </synopsis>
 
   <refsect2 id="R2-SQL-START-TRANSACTION-1">
@@ -77,52 +77,23 @@ WARNING:  BEGIN: already a transaction in progress
   <title>Description</title>
 
   <para>
-   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
-   <xref linkend="sql-begin" endterm="sql-begin-title"> command.
+   This command begins a new transaction. 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. In all other
+   respects, the behavior of this command is identical to the <xref
+   linkend="sql-begin" endterm="sql-begin-title"> command.
   </para>
 
  </refsect1>
 
- <refsect1>
-  <title>Notes</title>
-
-  <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 default isolation
-   level is used.
-  </para>
- </refsect1>
-
  <refsect1 id="R1-SQL-START-TRANSACTION-3">
   <title>Compatibility</title>
 
-  <refsect2 id="R2-SQL-START-TRANSACTION-4">
-   <title>SQL99</title>
-
-   <para>
-    <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 lack of predicate
-    locking, the <option>SERIALIZABLE</option> level is
-    not truly serializable. See the <citetitle>User's Guide</citetitle>
-    for details.
-   </para>
-
-   <para>
-    In <acronym>SQL99</acronym> this statement can specify two other
-    properties of the new transaction: whether the transaction is
-    read-only and the size of the diagnostics area. Neither of these
-    concepts are currently supported in
-    <productname>PostgreSQL</productname>.
-   </para>
-  </refsect2>
+  <para>
+   SQL99; but see also the compatibility section of <xref
+   linkend="sql-set-transaction" endterm="sql-set-transaction-title">.
+  </para>
  </refsect1>
 </refentry>
 
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index 55007a7d627..fd9a5e698f5 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.176 2003/01/08 00:22:26 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.177 2003/01/10 22:03:26 petere Exp $
 -->
 
 <appendix id="release">
@@ -36,6 +36,7 @@ System can use either hash- or sort-based strategy for grouped aggregation
 ON COMMIT options for temp tables
 extra_float_digits option allows pg_dump to dump float data accurately
 Long options for psql and pg_dump are now available on all platforms
+Read-only transactions
 ]]></literallayout>
 
  </sect1>