"David G. Johnston" <david.g.johns...@gmail.com> writes:
> Ok. That explains why "statement_timestamp() and transaction_timestamp()
> return the same value during the first command of a transaction," isn't
> just stating the obvious. transaction_timestamp() literally returns the
> value statement_timestamp().
Right. I'm tempted to be more explicit about that, along the lines of
<function>statement_timestamp()</function> and
<function>transaction_timestamp()</function>
- return the same value during the first statement of a transaction, but
might
- differ during subsequent statements.
+ return the same value during the first statement of a transaction,
+ because the transaction timestamp is set by copying the statement
+ timestamp when a new transaction starts.
I didn't include that change below though; perhaps it has too much
whiff of implementation detail.
> I'm fine with this entire section assuming/stating that extended protocol
> is in effect and that 53.2.2.1 explains how these behave when executing a
> multi-statement simple protocol "script".
It's incorrect to claim that this only applies to extended protocol,
and besides I thought you didn't want to mention protocol details
here. I can't argue with documenting it in the protocol chapter
though. So about like this?
regards, tom lane
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6b327d4fd81..5818457bf48 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11245,12 +11245,12 @@ now()
what it returns.
<function>statement_timestamp()</function> returns the start time of the current
statement (more specifically, the time of receipt of the latest command
- message from the client).
+ 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 4cfd9767f7c..f14bcdfcaeb 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -886,6 +886,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 typically result in them all observing the same
+ value of <function>transaction_timestamp()</function> as well,
+ except in the case where the query string ends a previously-started
+ transaction and begins a new one.
+ </para>
</sect3>
</sect2>
