agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Tom Lane <tgl@sss.pgh.pa.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: petermittere@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
Date: Mon, 14 Jul 2025 13:09:24 -0400
Message-ID: <697664.1752512964@sss.pgh.pa.us> (raw)
In-Reply-To: <CAKFQuwa2gDZTJm5hkrqubcn1=A3aTDR7HxX-NfF-9fKrp28f+A@mail.gmail.com>
References: <175223006802.3157505.14764328206246105568@wrigleys.postgresql.org>
<15139c5d218754350e4870062f90ff0e85490290.camel@cybertec.at>
<270191.1752420426@sss.pgh.pa.us>
<097e693ea6cc3541cbcd72c915d7d492c26930c0.camel@cybertec.at>
<456003.1752442676@sss.pgh.pa.us>
<458204.1752443813@sss.pgh.pa.us>
<CAKFQuwa4VMoHehuN5qCX5Jv15ZahTJ00jxMu4mbtYNHbJ4PXOA@mail.gmail.com>
<ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
<685003.1752506254@sss.pgh.pa.us>
<CAKFQuwYzod+L_vjOuWz8OAte2SoS5V5ByOGfhDx1-ubvHTb11g@mail.gmail.com>
<CAKFQuwYC-p=2pr__2Gu65HR5E=4fmiwHhacKBrxRYmB2GEqtGw@mail.gmail.com>
<690858.1752509326@sss.pgh.pa.us>
<CAKFQuwa2gDZTJm5hkrqubcn1=A3aTDR7HxX-NfF-9fKrp28f+A@mail.gmail.com>
"David G. Johnston" <david.g.johnston@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
Attachments:
[text/x-diff] v2-docs-clarify-current-timestamp-functions.patch (2.0K, ../697664.1752512964@sss.pgh.pa.us/2-v2-docs-clarify-current-timestamp-functions.patch)
download | inline diff:
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>
=
view thread (21+ messages) latest in thread
Message-ID: <697664.1752512964@sss.pgh.pa.us>
Permalink: ../697664.1752512964@sss.pgh.pa.us/
Also on: postgresql.org/message-id/697664.1752512964@sss.pgh.pa.us
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, david.g.johnston@gmail.com, laurenz.albe@cybertec.at, petermittere@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
In-Reply-To: <697664.1752512964@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox