doc: add mention of ssi read anomolies to mvcc docs

From Jeff Davis, modified by Kevin Grittner

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index d5c6076d4aa64ae3b899977447424197f1ef7bff..db820d6f43f278c526c3bd65ae07e56157e66fbb 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -515,8 +515,9 @@ ERROR:  could not serialize access due to concurrent update
    </indexterm>
 
    <para>
-    The <firstterm>Serializable</firstterm> isolation level provides the strictest transaction
-    isolation.  This level emulates serial transaction execution,
+    The <firstterm>Serializable</firstterm> isolation level provides
+    the strictest transaction isolation.  This level emulates serial
+    transaction execution for all committed transactions;
     as if transactions had been executed one after another, serially,
     rather than concurrently.  However, like the Repeatable Read level,
     applications using this level must
@@ -571,6 +572,20 @@ ERROR:  could not serialize access due to read/write dependencies among transact
     computed by A.
    </para>
 
+   <para>
+    When relying on Serializable transactions to prevent anomalies, it is
+    important that any data read from a permanent user table not be
+    considered valid until the transaction which read it has successfully
+    committed.  This is true even for read-only transactions, except that
+    data read within a <firstterm>deferrable</firstterm> read-only
+    transaction is known to be valid as soon as it is read, because such a
+    transaction waits until it can acquire a snapshot guaranteed to be free
+    from such problems before starting to read any data.  In all other cases
+    applications must not depend on results read during a transaction that
+    later aborted; instead, they should retry the transaction until it
+    succeeds.
+   </para>
+
    <para>
     To guarantee true serializability <productname>PostgreSQL</productname>
     uses <firstterm>predicate locking</>, which means that it keeps locks