Not sure if these would be considered redundant, since they don't add
any new information, but I think I would have found them helpful as a
reader.
From ec76436429bd7d1e3dddc0b26ba9b1539499f40b Mon Sep 17 00:00:00 2001
From: Will Mortensen <[email protected]>
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
