From ec76436429bd7d1e3dddc0b26ba9b1539499f40b Mon Sep 17 00:00:00 2001
From: Will Mortensen <will@extrahop.com>
Date: Sat, 27 Aug 2022 17:31:13 -0700
Subject: [PATCH 3/6] doc: discuss interaction between functions and Read
 Committed

---
 doc/src/sgml/mvcc.sgml  | 14 ++++++++++++++
 doc/src/sgml/xfunc.sgml | 10 +++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 512e8b710d..1382504fa9 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -464,6 +464,20 @@ COMMIT;
     sees an absolutely consistent view of the database.
    </para>
 
+   <para>
+    Within a procedure or <literal>VOLATILE</literal> function written in SQL or
+    any of the standard procedural languages, each command starts with a new
+    snapshot, so it may observe a different state of the database from other
+    commands within the function/procedure and from the command that is calling
+    the function. By contrast, commands within a <literal>STABLE</literal>
+    function use the snapshot established at the start of the command that is
+    calling the function, which also means they do not observe any data changes
+    made by the calling command. An <literal>IMMUTABLE</literal> function should
+    not select from tables that can ever change, and therefore should not itself
+    be affected by transaction isolation. See <xref linkend="xfunc-volatility"/>
+    for more details.
+   </para>
+
    <para>
     The partial transaction isolation provided by Read Committed mode
     is adequate for many applications, and this mode is fast and simple
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index cf5810b3c1..44a8021c21 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1704,8 +1704,11 @@ CREATE FUNCTION test(int, int) RETURNS int
     For functions written in SQL or in any of the standard procedural
     languages, there is a second important property determined by the
     volatility category, namely the visibility of any data changes that have
-    been made by the SQL command that is calling the function.  A
-    <literal>VOLATILE</literal> function will see such changes, a <literal>STABLE</literal>
+    been made either by the SQL command that is calling the function, or (if the
+    function is called in a transaction using the
+    <link linkend="xact-read-committed">Read Committed isolation level</link>)
+    by other transactions that have committed since the calling query
+    began. A <literal>VOLATILE</literal> function will see such changes, a <literal>STABLE</literal>
     or <literal>IMMUTABLE</literal> function will not.  This behavior is implemented
     using the snapshotting behavior of MVCC (see <xref linkend="mvcc"/>):
     <literal>STABLE</literal> and <literal>IMMUTABLE</literal> functions use a snapshot
@@ -1729,7 +1732,8 @@ CREATE FUNCTION test(int, int) RETURNS int
     <productname>PostgreSQL</productname> will execute all commands of a
     <literal>STABLE</literal> function using the snapshot established for the
     calling query, and so it will see a fixed view of the database throughout
-    that query.
+    that query, even within a transaction using the
+    <link linkend="xact-read-committed">Read Committed isolation level</link>.
    </para>
 
    <para>
-- 
2.25.1