Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1ubMgG-00HZE8-6i
	for pgsql-docs@arkaria.postgresql.org; Mon, 14 Jul 2025 17:09:32 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1ubMgE-00ACme-4l
	for pgsql-docs@arkaria.postgresql.org; Mon, 14 Jul 2025 17:09:30 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1ubMgD-00ACmM-Su
	for pgsql-docs@lists.postgresql.org; Mon, 14 Jul 2025 17:09:30 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by magus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1ubMgC-007eQZ-0g
	for pgsql-docs@lists.postgresql.org;
	Mon, 14 Jul 2025 17:09:30 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 56EH9OwU697665;
	Mon, 14 Jul 2025 13:09:24 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
cc: Laurenz Albe <laurenz.albe@cybertec.at>, petermittere@gmail.com,
        pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
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>
Comments: In-reply-to "David G. Johnston" <david.g.johnston@gmail.com>
	message dated "Mon, 14 Jul 2025 09:19:41 -0700"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <697607.1752512921.0@sss.pgh.pa.us>
Date: Mon, 14 Jul 2025 13:09:24 -0400
Message-ID: <697664.1752512964@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/697664.1752512964%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <697607.1752512921.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable

"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, bu=
t 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 protoco=
l
> 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


------- =_aaaaaaaaaa0
Content-Type: text/x-diff;
	name="v2-docs-clarify-current-timestamp-functions.patch";
	charset="us-ascii"
Content-ID: <697607.1752512921.2@sss.pgh.pa.us>
Content-Description: v2-docs-clarify-current-timestamp-functions.patch
Content-Transfer-Encoding: quoted-printable

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 comma=
nd
-    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, bu=
t might
+    differ during subsequent statements.
     <function>clock_timestamp()</function> returns the actual current tim=
e, 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>
 =


------- =_aaaaaaaaaa0--