Skip to content

Commit 75394d3

Browse files
tglsfdctglsfdc
committed
Fix breakage in new-in-7.3 timetz_zone() function: was giving random
results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
1 parent ca1d1b7 commit 75394d3

File tree

3 files changed

+195
-53
lines changed

3 files changed

+195
-53
lines changed

‎doc/src/sgml/datatype.sgml‎

Lines changed: 70 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.108 2002/11/15 03:11:15 momjian Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.109 2002/11/21 23:31:20 tgl Exp $
33
-->
44

55
<chapter id="datatype">
@@ -1569,19 +1569,31 @@ SELECT b, char_length(b) FROM test2;
15691569
<secondary>data type</secondary>
15701570
</indexterm>
15711571

1572+
<indexterm>
1573+
<primary>timestamp with time zone</primary>
1574+
<secondary>data type</secondary>
1575+
</indexterm>
1576+
15721577
<indexterm>
15731578
<primary>timestamp without time zone</primary>
15741579
<secondary>data type</secondary>
15751580
</indexterm>
15761581

15771582
<para>
1578-
Time stamp types exist as <type>timestamp [
1579-
(<replaceable>p</replaceable>) ]</type>, <type>timestamp [
1583+
The time stamp types are <type>timestamp [
15801584
(<replaceable>p</replaceable>) ] without time zone</type> and
1581-
<type>timestamp [ (<replaceable>p</replaceable>) ] without time
1582-
zone</type>. A plain <type>timestamp</type> is equivalent to
1583-
<type>timestamp without timezone</type>.
1585+
<type>timestamp [ (<replaceable>p</replaceable>) ] with time
1586+
zone</type>. Writing just <type>timestamp</type> is equivalent to
1587+
<type>timestamp without time zone</type>.
1588+
</para>
1589+
1590+
<note>
1591+
<para>
1592+
Prior to <productname>PostgreSQL</productname> 7.3, writing just
1593+
<type>timestamp</type> was equivalent to <type>timestamp with time
1594+
zone</type>. This was changed for SQL spec compliance.
15841595
</para>
1596+
</note>
15851597

15861598
<para>
15871599
Valid input for the time stamp types consists of a concatenation
@@ -1615,11 +1627,38 @@ January 8 04:05:06 1999 PST
16151627

16161628
<para>
16171629
For <type>timestamp without time zone</type>, any explicit time
1618-
zone specified in the input is silently swallowed. That is, the
1630+
zone specified in the input is silently ignored. That is, the
16191631
resulting date/time value is derived from the explicit date/time
16201632
fields in the input value, and is not adjusted for time zone.
16211633
</para>
16221634

1635+
<para>
1636+
For <type>timestamp with time zone</type>, the internally stored
1637+
value is always in UTC (GMT). An input value that has an explicit
1638+
time zone specified is converted to UTC using the appropriate offset
1639+
for that time zone. If no time zone is stated in the input string,
1640+
then it is assumed to be in the time zone indicated by the system's
1641+
<varname>TimeZone</> parameter, and is converted to UTC using the
1642+
offset for the <varname>TimeZone</> zone.
1643+
</para>
1644+
1645+
<para>
1646+
When a <type>timestamp with time
1647+
zone</type> value is output, it is always converted from UTC to the
1648+
current <varname>TimeZone</> zone, and displayed as local time in that
1649+
zone. To see the time in another time zone, either change
1650+
<varname>TimeZone</> or use the <literal>AT TIME ZONE</> construct
1651+
(see <xref linkend="functions-datetime-zoneconvert">).
1652+
</para>
1653+
1654+
<para>
1655+
Conversions between <type>timestamp without time zone</type> and
1656+
<type>timestamp with time zone</type> normally assume that the
1657+
<type>timestamp without time zone</type> value should be taken or given
1658+
as <varname>TimeZone</> local time. A different zone reference can
1659+
be specified for the conversion using <literal>AT TIME ZONE</>.
1660+
</para>
1661+
16231662
<table tocentry="1" id="datatype-timezone-table">
16241663
<title>Time Zone Input</title>
16251664
<tgroup cols="2">
@@ -1707,24 +1746,28 @@ January 8 04:05:06 1999 PST
17071746
<para>
17081747
The following <acronym>SQL</acronym>-compatible functions can be
17091748
used as date or time
1710-
input for the corresponding data type: <literal>CURRENT_DATE</literal>,
1749+
values for the corresponding data type: <literal>CURRENT_DATE</literal>,
17111750
<literal>CURRENT_TIME</literal>,
17121751
<literal>CURRENT_TIMESTAMP</literal>. The latter two accept an
1713-
optional precision specification. (See also <xref linkend="functions-datetime">.)
1752+
optional precision specification. (See also <xref linkend="functions-datetime-current">.)
17141753
</para>
17151754

17161755
<para>
17171756
<productname>PostgreSQL</productname> also supports several
1718-
special constants for convenience, shown in <xref
1719-
linkend="datatype-datetime-special-table">.
1757+
special date/time input values for convenience, as shown in <xref
1758+
linkend="datatype-datetime-special-table">. The values
1759+
<literal>infinity</literal> and <literal>-infinity</literal>
1760+
are specially represented inside the system and will be displayed
1761+
the same way; but the others are simply notational shorthands
1762+
that will be converted to ordinary date/time values when read.
17201763
</para>
17211764

17221765
<table id="datatype-datetime-special-table">
1723-
<title>Special Date/Time Constants</title>
1766+
<title>Special Date/Time Inputs</title>
17241767
<tgroup cols="2">
17251768
<thead>
17261769
<row>
1727-
<entry>Constant</entry>
1770+
<entry>Input string</entry>
17281771
<entry>Description</entry>
17291772
</row>
17301773
</thead>
@@ -1735,15 +1778,13 @@ January 8 04:05:06 1999 PST
17351778
</row>
17361779
<row>
17371780
<entry><literal>infinity</literal></entry>
1738-
<entry>later than other valid times</entry>
1781+
<entry>later than all other timestamps (not available for
1782+
type <type>date</>)</entry>
17391783
</row>
17401784
<row>
17411785
<entry><literal>-infinity</literal></entry>
1742-
<entry>earlier than other valid times</entry>
1743-
</row>
1744-
<row>
1745-
<entry><literal>invalid</literal></entry>
1746-
<entry>illegal entry</entry>
1786+
<entry>earlier than all other timestamps (not available for
1787+
type <type>date</>)</entry>
17471788
</row>
17481789
<row>
17491790
<entry><literal>now</literal></entry>
@@ -1962,13 +2003,21 @@ January 8 04:05:06 1999 PST
19622003
</para>
19632004

19642005
<para>
1965-
There are several ways to affect the time-zone behavior:
2006+
There are several ways to select the time zone used by the server:
19662007

19672008
<itemizedlist>
19682009
<listitem>
19692010
<para>
19702011
The <envar>TZ</envar> environment variable on the server host
1971-
is used by the server as the default time zone.
2012+
is used by the server as the default time zone, if no other is
2013+
specified.
2014+
</para>
2015+
</listitem>
2016+
2017+
<listitem>
2018+
<para>
2019+
The <varname>timezone</varname> configuration parameter can be
2020+
set in <filename>postgresql.conf</>.
19722021
</para>
19732022
</listitem>
19742023

@@ -1987,18 +2036,6 @@ January 8 04:05:06 1999 PST
19872036
sets the time zone for the session.
19882037
</para>
19892038
</listitem>
1990-
1991-
<listitem>
1992-
<para>
1993-
The construct
1994-
<programlisting>
1995-
<replaceable>timestamp</replaceable> AT TIME ZONE '<replaceable>zone</replaceable>'
1996-
</programlisting>
1997-
where <replaceable>zone</replaceable> can be specified as a
1998-
text time zone (e.g., <literal>'PST'</literal>) or as an
1999-
interval (e.g., <literal>INTERVAL '-08:00'</literal>).
2000-
</para>
2001-
</listitem>
20022039
</itemizedlist>
20032040
</para>
20042041

‎doc/src/sgml/func.sgml‎

Lines changed: 114 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.130 2002/11/11 20:14:02 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.131 2002/11/21 23:31:20 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -3549,9 +3549,14 @@ SUBSTRING('foobar' FROM 'o(.)b') <lineannotation>o</lineannotation>
35493549
<literal>*</literal>, etc.). For formatting functions, refer to
35503550
<xref linkend="functions-formatting">. You should be familiar with
35513551
the background information on date/time data types (see <xref
3552-
linkend="datatype-datetime">). The date/time operators described
3553-
below behave similarly for types involving time zones as well as
3554-
those without.
3552+
linkend="datatype-datetime">).
3553+
</para>
3554+
3555+
<para>
3556+
All the functions and operators described below that take time or timestamp
3557+
inputs actually come in two variants: one that takes time or timestamp
3558+
with time zone, and one that takes time or timestamp without time zone.
3559+
For brevity, these variants are not shown separately.
35553560
</para>
35563561

35573562
<table id="operators-datetime-table">
@@ -3771,7 +3776,7 @@ SUBSTRING('foobar' FROM 'o(.)b') <lineannotation>o</lineannotation>
37713776

37723777
<row>
37733778
<entry><function>now</function>()</entry>
3774-
<entry><type>timestamp</type></entry>
3779+
<entry><type>timestamp with time zone</type></entry>
37753780
<entry>Current date and time (equivalent to
37763781
<function>current_timestamp</function>); see <xref
37773782
linkend="functions-datetime-current">
@@ -3898,8 +3903,8 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
38983903
<listitem>
38993904
<para>
39003905
For <type>date</type> and <type>timestamp</type> values, the
3901-
number of seconds since 1970-01-01 00:00:00-00 (Result may be
3902-
negative.); for <type>interval</type> values, the total number
3906+
number of seconds since 1970-01-01 00:00:00-00 (can be negative);
3907+
for <type>interval</type> values, the total number
39033908
of seconds in the interval
39043909
</para>
39053910

@@ -4122,12 +4127,12 @@ SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
41224127
<para>
41234128
The <function>date_part</function> function is modeled on the traditional
41244129
<productname>Ingres</productname> equivalent to the
4125-
<acronym>SQL</acronym>-function <function>extract</function>:
4130+
<acronym>SQL</acronym>-standard function <function>extract</function>:
41264131
<synopsis>
41274132
date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
41284133
</synopsis>
4129-
Note that here the <replaceable>field</replaceable> value needs to
4130-
be a string. The valid field values for
4134+
Note that here the <replaceable>field</replaceable> parameter needs to
4135+
be a string value, not a name. The valid field values for
41314136
<function>date_part</function> are the same as for
41324137
<function>extract</function>.
41334138
</para>
@@ -4192,6 +4197,95 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
41924197
</para>
41934198
</sect2>
41944199

4200+
<sect2 id="functions-datetime-zoneconvert">
4201+
<title><function>AT TIME ZONE</function></title>
4202+
4203+
<indexterm>
4204+
<primary>timezone</primary>
4205+
<secondary>conversion</secondary>
4206+
</indexterm>
4207+
4208+
<para>
4209+
The <function>AT TIME ZONE</function> construct allows conversions
4210+
of timestamps to different timezones.
4211+
</para>
4212+
4213+
<table id="functions-datetime-zoneconvert-table">
4214+
<title>AT TIME ZONE Variants</title>
4215+
<tgroup cols="3">
4216+
<thead>
4217+
<row>
4218+
<entry>Expression</entry>
4219+
<entry>Returns</entry>
4220+
<entry>Description</entry>
4221+
</row>
4222+
</thead>
4223+
4224+
<tbody>
4225+
4226+
<row>
4227+
<entry>
4228+
<type>timestamp without time zone</type>
4229+
<literal>AT TIME ZONE</literal>
4230+
<replaceable>zone</>
4231+
</entry>
4232+
<entry><type>timestamp with time zone</type></entry>
4233+
<entry>Convert local time in given timezone to UTC</entry>
4234+
</row>
4235+
4236+
<row>
4237+
<entry>
4238+
<type>timestamp with time zone</type>
4239+
<literal>AT TIME ZONE</literal>
4240+
<replaceable>zone</>
4241+
</entry>
4242+
<entry><type>timestamp without time zone</type></entry>
4243+
<entry>Convert UTC to local time in given timezone</entry>
4244+
</row>
4245+
4246+
<row>
4247+
<entry>
4248+
<type>time with time zone</type>
4249+
<literal>AT TIME ZONE</literal>
4250+
<replaceable>zone</>
4251+
</entry>
4252+
<entry><type>time with time zone</type></entry>
4253+
<entry>Convert local time across timezones</entry>
4254+
</row>
4255+
4256+
</tbody>
4257+
</tgroup>
4258+
</table>
4259+
4260+
<para>
4261+
In these expressions, the desired time <replaceable>zone</> can be
4262+
specified either as a text string (e.g., <literal>'PST'</literal>)
4263+
or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>).
4264+
</para>
4265+
4266+
<para>
4267+
Examples (supposing that <varname>TimeZone</> is <literal>PST8PDT</>):
4268+
<screen>
4269+
SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
4270+
<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computeroutput>
4271+
4272+
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
4273+
<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computeroutput>
4274+
</screen>
4275+
The first example takes a zone-less timestamp and interprets it as MST time
4276+
(GMT-7) to produce a UTC timestamp, which is then rotated to PST (GMT-8)
4277+
for display. The second example takes a timestamp specified in EST
4278+
(GMT-5) and converts it to local time in MST (GMT-7).
4279+
</para>
4280+
4281+
<para>
4282+
The function <function>timezone</function>(<replaceable>zone</>,
4283+
<replaceable>timestamp</>) is equivalent to the SQL-compliant construct
4284+
<replaceable>timestamp</> <literal>AT TIME ZONE</literal>
4285+
<replaceable>zone</>.
4286+
</para>
4287+
</sect2>
4288+
41954289
<sect2 id="functions-datetime-current">
41964290
<title>Current Date/Time</title>
41974291

@@ -4219,6 +4313,16 @@ LOCALTIMESTAMP
42194313
LOCALTIME ( <replaceable>precision</replaceable> )
42204314
LOCALTIMESTAMP ( <replaceable>precision</replaceable> )
42214315
</synopsis>
4316+
</para>
4317+
4318+
<para>
4319+
<function>CURRENT_TIME</function> and
4320+
<function>CURRENT_TIMESTAMP</function> deliver values with time zone;
4321+
<function>LOCALTIME</function> and
4322+
<function>LOCALTIMESTAMP</function> deliver values without time zone.
4323+
</para>
4324+
4325+
<para>
42224326
<function>CURRENT_TIME</function>,
42234327
<function>CURRENT_TIMESTAMP</function>,
42244328
<function>LOCALTIME</function>, and

0 commit comments

Comments
 (0)