Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 11bba6e

Browse files
committed
Doc: clarify behavior of timestamptz input some more.
Try to make it absolutely plain that we don't retain the originally specified time zone, only the UTC timestamp. While at it, make glossary entries for "UTC" and "GMT". Author: Robert Treat <rob@xzilla.net> Co-authored-by: Tom Lane <tgl@sss.pgh.pa.us> Discussion: https://postgr.es/m/173796426022.1064.9135167366862649513@wrigleys.postgresql.org Backpatch-through: 13
1 parent b92c033 commit 11bba6e

File tree

2 files changed

+26
-7
lines changed

2 files changed

+26
-7
lines changed

doc/src/sgml/datatype.sgml

+10-7
Original file line numberDiff line numberDiff line change
@@ -2245,24 +2245,27 @@ TIMESTAMP '2004-10-19 10:23:54+02'
22452245
<programlisting>
22462246
TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
22472247
</programlisting>
2248+
</para>
22482249

2249-
In a literal that has been determined to be <type>timestamp without time
2250+
<para>
2251+
In a value that has been determined to be <type>timestamp without time
22502252
zone</type>, <productname>PostgreSQL</productname> will silently ignore
22512253
any time zone indication.
22522254
That is, the resulting value is derived from the date/time
2253-
fields in the input value, and is not adjusted for time zone.
2255+
fields in the input string, and is not adjusted for time zone.
22542256
</para>
22552257

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

22682271
<para>

doc/src/sgml/glossary.sgml

+16
Original file line numberDiff line numberDiff line change
@@ -851,6 +851,11 @@
851851
</glossdef>
852852
</glossentry>
853853

854+
<glossentry>
855+
<glossterm>GMT</glossterm>
856+
<glosssee otherterm="glossary-utc" />
857+
</glossentry>
858+
854859
<glossentry id="glossary-grant">
855860
<glossterm>Grant</glossterm>
856861
<glossdef>
@@ -2047,6 +2052,17 @@
20472052
</glossdef>
20482053
</glossentry>
20492054

2055+
<glossentry id="glossary-utc">
2056+
<glossterm>UTC</glossterm>
2057+
<glossdef>
2058+
<para>
2059+
Universal Coordinated Time, the primary global time reference,
2060+
approximately the time prevailing at the zero meridian of longitude.
2061+
Often but inaccurately referred to as GMT (Greenwich Mean Time).
2062+
</para>
2063+
</glossdef>
2064+
</glossentry>
2065+
20502066
<glossentry id="glossary-vacuum">
20512067
<glossterm>Vacuum</glossterm>
20522068
<glossdef>

0 commit comments

Comments
 (0)