Doc: Add references for SI and SSI.

Our documentation failed to point out that REPEATABLE READ is really
snapshot isolation, which might be important to some users.  Point to
the standard reference paper for this complicated topic.

Likewise, add a reference to the VLDB paper about PostgreSQL SSI, for
technical information about our SSI implementation and how it compares
to S2PL.

While here, add a note about catalog access using a lower isolation
level, per recent user complaint.

Back-patch to all releases.

Reported-by: Kyle Kingsbury 
Reviewed-by: Andres Freund 
Reviewed-by: Peter Geoghegan 
Reviewed-by: Tatsuo Ishii 
Discussion: https://postgr.es/m/db7b729d-0226-d162-a126-8a8ab2dc4443%40jepsen.io
Discussion: https://postgr.es/m/16454-9408996bb1750faf%40postgresql.org

diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml
index b40c06eb38de539451c6b6b2af7b737dd0e3f61c..e72a65ff8aa87d8dcaa42ec70c2cd883913cc6f4 100644 (file)
--- a/doc/src/sgml/biblio.sgml
+++ b/doc/src/sgml/biblio.sgml
@@ -230,6 +230,64 @@ [email protected]
   
    Proceedings and Articles
 
+   
+    
+     <ulink url="https://arxiv.org/pdf/1208.4179">Serializable Snapshot Isolation in PostgreSQL</ulink>
+     
+      
+       D.
+       Ports
+      
+      
+       K.
+       Grittner
+      
+     
+    
+    
+     VLDB Conference
+     August 2012
+     Istanbul, Turkey
+    
+   
+
+   
+    
+     <ulink url="https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf">A Critique of ANSI SQL Isolation Levels</ulink>
+     
+      
+       H.
+       Berenson
+      
+      
+       P.
+       Bernstein
+      
+      
+       J.
+       Gray
+      
+      
+       J.
+       Melton
+      
+      
+       E.
+       O'Neil
+      
+      
+       P.
+       O'Neil
+      
+     
+    
+    
+     ACM-SIGMOD Conference on Management of Data
+     June 1995
+     San Jose, California
+    
+   
+
    
     Partial indexing in POSTGRES: research project
     

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index a826f2b4e470703b5bcb9d82d7bac8fc606cca52..dda6f1f2adbe006139329578efd8984e3c8daed2 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -535,6 +535,20 @@ ERROR:  could not serialize access due to concurrent update
     of explicit locks to block conflicting transactions.
    
 
+   
+    The Repeatable Read isolation level is implemented using a technique
+    known in academic database literature and in some other database products
+    as Snapshot Isolation.  Differences in behavior
+    and performance may be observed when compared with systems that use a
+    traditional locking technique that reduces concurrency.  Some other
+    systems may even offer Repeatable Read and Snapshot Isolation as distinct
+    isolation levels with different behavior.  The permitted phenomena that
+    distinguish the two techniques were not formalized by database researchers
+    until after the SQL standard was developed, and are outside the scope of
+    this manual.  For a full treatment, please see
+    .
+   
+
    
     
      Prior to PostgreSQL version 9.1, a request
@@ -783,6 +797,15 @@ ERROR:  could not serialize access due to read/write dependencies among transact
      
     
    
+
+   
+    The Serializable isolation level is implemented using a technique known
+    in academic database literature as Serializable Snapshot Isolation, which
+    builds on Snapshot Isolation by adding checks for serialization anomalies.
+    Some differences in behavior and performance may be observed when compared
+    with other systems that use a traditional locking technique.  Please see
+     for detailed information.
+   
   
  
 
@@ -1726,6 +1749,16 @@ SELECT pg_advisory_lock(q.id) FROM
     see a transient state that is inconsistent with any serial execution
     of the transactions on the master.
    
+
+   
+    Internal access to the system catalogs is not done using the isolation
+    level of the current transaction.  This means that newly created database
+    objects such as tables are visible to concurrent Repeatable Read and
+    Serializable transactions, even though the rows they contain are not.  In
+    contrast, queries that explicitly examine the system catalogs don't see
+    rows representing concurrently created database objects, in the higher
+    isolation levels.
+