From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Treat <rob@xzilla.net>
cc: =?UTF-8?Q?=C3=81lvaro_Herrera?= <alvherre@alvh.no-ip.org>,
        Laurenz Albe <laurenz.albe@cybertec.at>, bristleconeweb@gmail.com,
        pgsql-docs@lists.postgresql.org
Subject: Re: timestamp with time zone ~> GMT
In-reply-to: 
 <CAJSLCQ2iBj9-CXbodCL=wJoLt3oD+n0F8ZdjEV7bLUNJfLmTOg@mail.gmail.com>
References: <202502031621.j4h5q2bp3orj@alvherre.pgsql>
 <410526.1738603387@sss.pgh.pa.us>
 <CAJSLCQ2iBj9-CXbodCL=wJoLt3oD+n0F8ZdjEV7bLUNJfLmTOg@mail.gmail.com>
Comments: In-reply-to Robert Treat <rob@xzilla.net>
	message dated "Mon, 03 Feb 2025 16:43:04 -0500"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <1209626.1738881174.0@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Thu, 06 Feb 2025 17:33:47 -0500
Message-ID: <1209685.1738881227@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/1209685.1738881227%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <1209626.1738881174.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit

Robert Treat <rob@xzilla.net> writes:
> On Mon, Feb 3, 2025 at 12:23 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Hmm, I kind of like the up-front statement that timestamptz stores
>> UTC.  How about this simpler change?

> I thought the re-order made sense since the preceding paragraph talks
> exclusively about behavior, so this paragraph first contrasts the
> behavioral difference between the two, and then mentions the storage
> aspects as part of that story.
> I actually like the above as well, but if it were me I'd move all
> mentions of storage (the existing + the above) to the end of the
> paragraph after the behavior aspects.

OK, it makes more sense when considering the previous para as well.
Here's a combined proposal that also adds glossary entries.

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff;
	name="v2-0001-Clarify-timestamptz-input-time-zone-behavior.patch";
	charset="us-ascii"
Content-ID: <1209626.1738881174.2@sss.pgh.pa.us>
Content-Description: 
 v2-0001-Clarify-timestamptz-input-time-zone-behavior.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 1d9127e94e..b20241feb5 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2245,24 +2245,27 @@ TIMESTAMP '2004-10-19 10:23:54+02'
 <programlisting>
 TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
 </programlisting>
+     </para>
 =

-      In a literal that has been determined to be <type>timestamp without=
 time
+     <para>
+      In a value that has been determined to be <type>timestamp without t=
ime
       zone</type>, <productname>PostgreSQL</productname> will silently ig=
nore
       any time zone indication.
       That is, the resulting value is derived from the date/time
-      fields in the input value, and is not adjusted for time zone.
+      fields in the input string, and is not adjusted for time zone.
      </para>
 =

      <para>
-      For <type>timestamp with time zone</type>, the internally stored
-      value is always in UTC (Universal
-      Coordinated Time, traditionally known as Greenwich Mean Time,
-      <acronym>GMT</acronym>).  An input value that has an explicit
-      time zone specified is converted to UTC using the appropriate offse=
t
+      For <type>timestamp with time zone</type> values, an input string
+      that includes an explicit time zone will be converted to UTC
+      (<glossterm linkend=3D"glossary-utc">Universal Coordinated
+      Time</glossterm>) using the appropriate offset
       for that time zone.  If no time zone is stated in the input string,
       then it is assumed to be in the time zone indicated by the system's
       <xref linkend=3D"guc-timezone"/> parameter, and is converted to UTC=
 using the
       offset for the <varname>timezone</varname> zone.
+      In either case, the value is stored internally as UTC, and the
+      originally stated or assumed time zone is not retained.
      </para>
 =

      <para>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index f54f25c1c6..c0f812e3f5 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -851,6 +851,11 @@
    </glossdef>
   </glossentry>
 =

+  <glossentry>
+   <glossterm>GMT</glossterm>
+   <glosssee otherterm=3D"glossary-utc" />
+  </glossentry>
+
   <glossentry id=3D"glossary-grant">
    <glossterm>Grant</glossterm>
    <glossdef>
@@ -2047,6 +2052,17 @@
    </glossdef>
   </glossentry>
 =

+  <glossentry id=3D"glossary-utc">
+   <glossterm>UTC</glossterm>
+   <glossdef>
+    <para>
+     Universal Coordinated Time, the primary global time reference,
+     approximately the time prevailing at the zero meridian of longitude.
+     Often but inaccurately referred to as GMT (Greenwich Mean Time).
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id=3D"glossary-vacuum">
    <glossterm>Vacuum</glossterm>
    <glossdef>

------- =_aaaaaaaaaa0--