database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-27 22:56:53 +03:00
Code

Doc: clarify behavior of timestamptz input some more.

Browse Source 
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
This commit is contained in:
Tom Lane 2025-02-07 12:40:41 -05:00
parent b92c03342d
commit 11bba6e494
2 changed files with 30 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/src/sgml/datatype.sgml
View File

@ -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>
In a literal that has been determined to be <type>timestamp without time
zone</type>, <productname>PostgreSQL</productname> will silently ignore
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.
</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 offset
In a value that has been determined to be <type>timestamp without time
zone</type>, <productname>PostgreSQL</productname> will silently ignore
any time zone indication.
That is, the resulting value is derived from the date/time
fields in the input string, and is not adjusted for time zone.
</para>
<para>
For <type>timestamp with time zone</type> values, an input string
that includes an explicit time zone will be converted to UTC
(<glossterm linkend="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="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>

16
doc/src/sgml/glossary.sgml
View File

@ -851,6 +851,11 @@
</glossdef>
</glossentry>
<glossentry>
<glossterm>GMT</glossterm>
<glosssee otherterm="glossary-utc" />
</glossentry>
<glossentry id="glossary-grant">
<glossterm>Grant</glossterm>
<glossdef>
@ -2047,6 +2052,17 @@
</glossdef>
</glossentry>
<glossentry id="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="glossary-vacuum">
<glossterm>Vacuum</glossterm>
<glossdef>