From 5ea9d9ac0c332b79dc4d51e093e1daef46ddcf61 Mon Sep 17 00:00:00 2001 From: Tom Lane 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 Author: Tom Lane Reviewed-by: Laurenz Albe Reviewed-by: David G. Johnston Discussion: http://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 e2bc769e50b..db22327ac12 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -10689,10 +10689,10 @@ now() statement (more specifically, the time of receipt of the latest command message from the client). statement_timestamp() and transaction_timestamp() - 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. clock_timestamp() 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. timeofday() is a historical PostgreSQL function. Like clock_timestamp(), it returns the actual current time, diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index fdf34eba10c..e030b55186c 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -818,6 +818,16 @@ SELCT 1/0; Errors detected at semantic analysis or later, such as a misspelled table or column name, do not have this effect. + + + Lastly, note that all the statements within the Query message will + observe the same value of statement_timestamp(), + since that timestamp is updated only upon receipt of the Query + message. This will result in them all observing the same + value of transaction_timestamp() as well, + except in cases where the query string ends a previously-started + transaction and begins a new one. + -- 2.39.5