Skip to content

Commit 0e2cc38

Browse files
committed
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
1 parent 093d3d7 commit 0e2cc38

File tree

2 files changed

+13
-3
lines changed

2 files changed

+13
-3
lines changed

doc/src/sgml/func.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10067,10 +10067,10 @@ now()
1006710067
statement (more specifically, the time of receipt of the latest command
1006810068
message from the client).
1006910069
<function>statement_timestamp()</function> and <function>transaction_timestamp()</function>
10070-
return the same value during the first command of a transaction, but might
10071-
differ during subsequent commands.
10070+
return the same value during the first statement of a transaction, but might
10071+
differ during subsequent statements.
1007210072
<function>clock_timestamp()</function> returns the actual current time, and
10073-
therefore its value changes even within a single SQL command.
10073+
therefore its value changes even within a single SQL statement.
1007410074
<function>timeofday()</function> is a historical
1007510075
<productname>PostgreSQL</productname> function. Like
1007610076
<function>clock_timestamp()</function>, it returns the actual current time,

doc/src/sgml/protocol.sgml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -818,6 +818,16 @@ SELCT 1/0;<!-- this typo is intentional -->
818818
Errors detected at semantic analysis or later, such as a misspelled
819819
table or column name, do not have this effect.
820820
</para>
821+
822+
<para>
823+
Lastly, note that all the statements within the Query message will
824+
observe the same value of <function>statement_timestamp()</function>,
825+
since that timestamp is updated only upon receipt of the Query
826+
message. This will result in them all observing the same
827+
value of <function>transaction_timestamp()</function> as well,
828+
except in cases where the query string ends a previously-started
829+
transaction and begins a new one.
830+
</para>
821831
</sect3>
822832
</sect2>
823833

0 commit comments

Comments
 (0)