From bdb052f53b1afc3218f0993cadecdcd4df94f903 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 15 Jul 2025 16:35:42 -0400
Subject: [PATCH] Doc: clarify description of current-date/time functions.

Minor wordsmithing of the func.sgml paragraph describing
statement_timestamp() and allied functions: don't switch between
"statement" and "command" when those are being used to mean about
the same thing.

Also, add some text to protocol.sgml describing the perhaps-surprising
behavior these functions have in a multi-statement Query message.

Reported-by: P M <petermittere@gmail.com>
Author: Tom Lane <tgl@sss.pgh.pa.us>
Reviewed-by: Laurenz Albe <laurenz.albe@cybertec.at>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Discussion: https://postgr.es/m/175223006802.3157505.14764328206246105568@wrigleys.postgresql.org
Backpatch-through: 13
---
 doc/src/sgml/func.sgml     |  6 +++---
 doc/src/sgml/protocol.sgml | 10 ++++++++++
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 9db19c5d4ab..fc4b9537871 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11024,10 +11024,10 @@ now()
     statement (more specifically, the time of receipt of the latest command
     message from the client).
     <function>statement_timestamp()</function> and <function>transaction_timestamp()</function>
-    return the same value during the first command of a transaction, but might
-    differ during subsequent commands.
+    return the same value during the first statement of a transaction, but might
+    differ during subsequent statements.
     <function>clock_timestamp()</function> returns the actual current time, and
-    therefore its value changes even within a single SQL command.
+    therefore its value changes even within a single SQL statement.
     <function>timeofday()</function> is a historical
     <productname>PostgreSQL</productname> function.  Like
     <function>clock_timestamp()</function>, it returns the actual current time,
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 1b1894e9751..3a69acfa59c 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -800,6 +800,16 @@ SELCT 1/0;<!-- this typo is intentional -->
      Errors detected at semantic analysis or later, such as a misspelled
      table or column name, do not have this effect.
     </para>
+
+    <para>
+     Lastly, note that all the statements within the Query message will
+     observe the same value of <function>statement_timestamp()</function>,
+     since that timestamp is updated only upon receipt of the Query
+     message.  This will result in them all observing the same
+     value of <function>transaction_timestamp()</function> as well,
+     except in cases where the query string ends a previously-started
+     transaction and begins a new one.
+    </para>
    </sect3>
   </sect2>