aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
authorTom Lane <tgl@sss.pgh.pa.us>2025-02-07 12:40:41 -0500
committerTom Lane <tgl@sss.pgh.pa.us>2025-02-07 12:40:41 -0500
commit11bba6e49407cbaa3a9cd317bb3a1f08b8c5609b (patch)
tree4c4af2399aba93cc749be4d355b1cc1f714f1b1e /doc/src
parentb92c03342dcd69d259262b06b5c290e27249cb11 (diff)
downloadpostgresql-11bba6e49407cbaa3a9cd317bb3a1f08b8c5609b.tar.gz
postgresql-11bba6e49407cbaa3a9cd317bb3a1f08b8c5609b.zip
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
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/datatype.sgml17
-rw-r--r--doc/src/sgml/glossary.sgml16
2 files changed, 26 insertions, 7 deletions
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 1d9127e94e4..b20241feb50 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 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.
+ 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 offset
+ 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>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index f54f25c1c6b..c0f812e3f5e 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="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>