From 3ef86a34e84d4dcae2f365f7a2502bebaf3b701b Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@gmail.com>
Date: Thu, 11 Jun 2020 17:29:08 +1200
Subject: [PATCH] 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, which
for those interested in reading about the differences between SSI and
S2PL, and further papers referenced from there.

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

Reported-by: Kyle Kingsbury <aphyr@jepsen.io>
Discussion: https://postgr.es/m/db7b729d-0226-d162-a126-8a8ab2dc4443%40jepsen.io
Discussion: https://postgr.es/m/16454-9408996bb1750faf%40postgresql.org
---
 doc/src/sgml/biblio.sgml | 54 ++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/mvcc.sgml   | 25 +++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml
index b40c06eb38..e1ea912106 100644
--- a/doc/src/sgml/biblio.sgml
+++ b/doc/src/sgml/biblio.sgml
@@ -230,6 +230,60 @@ ssimkovi@ag.or.at
   <bibliodiv>
    <title>Proceedings and Articles</title>
 
+   <biblioentry id="gritt2012">
+    <title><ulink url="https://arxiv.org/pdf/1208.4179">Serializable Snapshot Isolation in PostgreSQL</ulink></title>
+    <authorgroup>
+     <author>
+      <firstname>Dan</firstname>
+      <surname>Ports</surname>
+     </author>
+     <author>
+      <firstname>Kevin</firstname>
+      <surname>Grittner</surname>
+     </author>
+    </authorgroup>
+    <publisher>
+     <publishername>Proceedings of the VLDB Endowment (PVLDB)</publishername>
+    </publisher>
+    <seriesvolnums>Vol. 5, No. 12, pp. 1850-1861</seriesvolnums>
+    <pubdate>2012</pubdate>
+   </biblioentry>
+
+   <biblioentry id="berenson95">
+    <title><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></title>
+    <authorgroup>
+     <author>
+      <firstname>Hal</firstname>
+      <surname>Berenson</surname>
+     </author>
+     <author>
+      <firstname>Phil</firstname>
+      <surname>Bernstein</surname>
+     </author>
+     <author>
+      <firstname>Jim</firstname>
+      <surname>Gray</surname>
+     </author>
+     <author>
+      <firstname>Jim</firstname>
+      <surname>Melton</surname>
+     </author>
+     <author>
+      <firstname>Elizabeth</firstname>
+      <surname>O'Neil</surname>
+     </author>
+     <author>
+      <firstname>Patrick</firstname>
+      <surname>O'Neil</surname>
+     </author>
+    </authorgroup>
+    <pubsnumber>MSR-TR-95-51</pubsnumber>
+    <publisher>
+     <publishername>Microsoft Research</publishername>
+    </publisher>
+    <pubdate>June 1995</pubdate>
+   </biblioentry>
+
    <biblioentry id="olson93">
     <title>Partial indexing in POSTGRES: research project</title>
     <authorgroup>
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index a826f2b4e4..0622c6ff51 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -535,6 +535,15 @@ ERROR:  could not serialize access due to concurrent update
     of explicit locks to block conflicting transactions.
    </para>
 
+   <para>
+    The Repeatable Read isolation level is implemented using a technique
+    known in academic database literature and in some other database products
+    as <firstterm>Snapshot Isolation</firstterm>.  Differences in behavior
+    may be observed when compared with systems using other implementation
+    techniques.  For a full treatment, please see
+    <xref linkend="berenson95"/>.
+   </para>
+
    <note>
     <para>
      Prior to <productname>PostgreSQL</productname> version 9.1, a request
@@ -783,6 +792,15 @@ ERROR:  could not serialize access due to read/write dependencies among transact
      </listitem>
     </itemizedlist>
    </para>
+
+   <para>
+    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 may be observed when compared
+    with systems using other techniques.  Please see
+    <xref linkend="gritt2012"/> for detailed information.
+   </para>
   </sect2>
  </sect1>
 
@@ -1726,6 +1744,13 @@ SELECT pg_advisory_lock(q.id) FROM
     see a transient state that is inconsistent with any serial execution
     of the transactions on the master.
    </para>
+
+   <para>
+    Access to the system catalogs is not done using the isolation level
+    of the current transaction.  This has the effect that newly created
+    database objects such as tables become visible to concurrent Repeatable
+    Read and Serializable transactions, even though their contents does not.
+   </para>
   </sect1>
 
   <sect1 id="locking-indexes">
-- 
2.20.1

