Add a warning about possible strange behavior of volatile functions

in cursors.  This has always been the case, but given the lack of user
complaints about it, I'm not going to bother back-patching this.

diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml
index 96e1f7d272b76e528f8f570fc1673e4fe6c5f497..b7451bfb40d9acc617ce83e9ce0488d6fe79bfe4 100644 (file)
--- a/doc/src/sgml/ref/declare.sgml
+++ b/doc/src/sgml/ref/declare.sgml
@@ -228,6 +228,20 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
     <literal>SCROLL</literal> may not be specified in this case.
    </para>
 
+   <caution>
+    <para>
+     Scrollable and <literal>WITH HOLD</literal> cursors may give unexpected
+     results if they invoke any volatile functions (see <xref
+     linkend="xfunc-volatility">).  When a previously fetched row is
+     re-fetched, the functions might be re-executed, perhaps leading to
+     results different from the first time.  One workaround for such cases
+     is to declare the cursor <literal>WITH HOLD</literal> and commit the
+     transaction before reading any rows from it.  This will force the
+     entire output of the cursor to be materialized in temporary storage,
+     so that volatile functions are executed exactly once for each row.
+    </para>
+   </caution>
+
    <para>
     If the cursor's query includes <literal>FOR UPDATE</> or <literal>FOR
     SHARE</>, then returned rows are locked at the time they are first