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 <w...@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