doc: clarify how TIMESTAMP WITH TIME ZONE behaves

Mention "time zone conversion" as a way to clarify the time zone is not
stored in the database.

Reported-by: Richard Neill
Discussion: https://postgr.es/m/ddf41f033a8add84e1f28a095defafae@richardneill.org

Backpatch-through: 19

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index cc32f2e8165a5e307627fdbc0b1b8a41074736fa..89985ab7b16d018644b0560141c0307e91e04514 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -264,13 +264,13 @@
       <row>
        <entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
        <entry></entry>
-       <entry>date and time (no time zone)</entry>
+       <entry>date and time (no time zone conversion)</entry>
       </row>
 
       <row>
        <entry><type>timestamp [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
        <entry><type>timestamptz</type></entry>
-       <entry>date and time, including time zone</entry>
+       <entry>date and time, including time zone conversion</entry>
       </row>
 
       <row>
@@ -1768,7 +1768,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea;
        <row>
         <entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
         <entry>8 bytes</entry>
-        <entry>both date and time (no time zone)</entry>
+        <entry>both date and time (no time zone conversion)</entry>
         <entry>4713 BC</entry>
         <entry>294276 AD</entry>
         <entry>1 microsecond</entry>
@@ -1776,7 +1776,7 @@ SELECT 'abc \153\154\155 \052\251\124'::bytea;
        <row>
         <entry><type>timestamp [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
         <entry>8 bytes</entry>
-        <entry>both date and time, with time zone</entry>
+        <entry>both date and time, with time zone conversion</entry>
         <entry>4713 BC</entry>
         <entry>294276 AD</entry>
         <entry>1 microsecond</entry>
@@ -2263,8 +2263,9 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
       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.
+      In either case, the value is stored internally as UTC.  The
+      originally stated or assumed time zone is not retained and
+      <emphasis>cannot</emphasis> be retrieved later.
      </para>
 
      <para>