mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-01-06 15:24:56 +08:00
Include specific info on available timezones.
Document date/time input parsing procedure.
This commit is contained in:
Thomas G. Lockhart
parent
2289b403aa
commit
1def28ff20
@ -516,214 +516,226 @@ This is set at compile time and may change in a future release.
|
|||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Date/Time Types</title>
|
<title>Date/Time Types</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are two fundamental kinds of date and time measurements:
|
There are two fundamental kinds of date and time measurements
|
||||||
absolute clock times and relative time intervals.
|
provided by <productname>Postgres</productname>:
|
||||||
Both kinds of quantities should have behaviors demonstrating both
|
absolute clock times and relative time intervals.
|
||||||
continuity and smoothness.
|
Both kinds of time measurements should demonstrate both
|
||||||
<productname>Postgres</productname> supplies two primary user-oriented
|
continuity and smoothness.
|
||||||
date and time types,
|
</para>
|
||||||
<type>datetime</type> and <type>timespan</type>, as well as
|
|
||||||
the related <acronym>SQL92</acronym> types <type>timestamp</type>,
|
|
||||||
<type>interval</type>,
|
|
||||||
<type>date</type> and <type>time</type>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In a future release, <type>datetime</type> and <type>timespan</type> are likely
|
<productname>Postgres</productname> supplies two primary user-oriented
|
||||||
to merge with the <acronym>SQL92</acronym> types <type>timestamp</type>,
|
date and time types,
|
||||||
<type>interval</type>.
|
<type>datetime</type> and <type>timespan</type>, as well as
|
||||||
Other date and time types are also available, mostly
|
the related <acronym>SQL92</acronym> types <type>timestamp</type>,
|
||||||
for historical reasons.
|
<type>interval</type>,
|
||||||
</para>
|
<type>date</type> and <type>time</type>.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<table tocentry="1">
|
In a future release, <type>datetime</type> and <type>timespan</type> are likely
|
||||||
<title><productname>Postgres</productname> Date/Time Types</title>
|
to merge with the <acronym>SQL92</acronym> types <type>timestamp</type>,
|
||||||
<titleabbrev>Date/Time</titleabbrev>
|
<type>interval</type>.
|
||||||
<tgroup cols="4">
|
Other date and time types are also available, mostly
|
||||||
<thead>
|
for historical reasons.
|
||||||
<row>
|
</para>
|
||||||
<entry>Date/Time Type</entry>
|
|
||||||
<entry>Storage</entry>
|
|
||||||
<entry>Recommendation</entry>
|
|
||||||
<entry>Description</entry>
|
|
||||||
</row>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<row>
|
|
||||||
<entry>abstime</entry>
|
|
||||||
<entry>4 bytes</entry>
|
|
||||||
<entry>original date and time</entry>
|
|
||||||
<entry>limited range</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>date</entry>
|
|
||||||
<entry>4 bytes</entry>
|
|
||||||
<entry><acronym>SQL92</acronym> type</entry>
|
|
||||||
<entry>wide range</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>datetime</entry>
|
|
||||||
<entry>8 bytes</entry>
|
|
||||||
<entry>best general date and time</entry>
|
|
||||||
<entry>wide range, high precision</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>interval</entry>
|
|
||||||
<entry>12 bytes</entry>
|
|
||||||
<entry><acronym>SQL92</acronym> type</entry>
|
|
||||||
<entry>equivalent to timespan</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>reltime</entry>
|
|
||||||
<entry>4 bytes</entry>
|
|
||||||
<entry>original time interval</entry>
|
|
||||||
<entry>limited range, low precision</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>time</entry>
|
|
||||||
<entry>4 bytes</entry>
|
|
||||||
<entry><acronym>SQL92</acronym> type</entry>
|
|
||||||
<entry>wide range</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>timespan</entry>
|
|
||||||
<entry>12 bytes</entry>
|
|
||||||
<entry>best general time interval</entry>
|
|
||||||
<entry>wide range, high precision</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>timestamp</entry>
|
|
||||||
<entry>4 bytes</entry>
|
|
||||||
<entry><acronym>SQL92</acronym> type</entry>
|
|
||||||
<entry>limited range</entry>
|
|
||||||
</row>
|
|
||||||
</tbody>
|
|
||||||
</tgroup>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
<type>timestamp</type> is currently implemented separately from
|
<para>
|
||||||
<type>datetime</type>, although they share input and output routines.
|
<table tocentry="1">
|
||||||
</para>
|
<title><productname>Postgres</productname> Date/Time Types</title>
|
||||||
|
<titleabbrev>Date/Time</titleabbrev>
|
||||||
|
<tgroup cols="4">
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>Date/Time Type</entry>
|
||||||
|
<entry>Storage</entry>
|
||||||
|
<entry>Recommendation</entry>
|
||||||
|
<entry>Description</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>abstime</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>original date and time</entry>
|
||||||
|
<entry>limited range</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>date</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry><acronym>SQL92</acronym> type</entry>
|
||||||
|
<entry>wide range</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>datetime</entry>
|
||||||
|
<entry>8 bytes</entry>
|
||||||
|
<entry>best general date and time</entry>
|
||||||
|
<entry>wide range, high precision</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>interval</entry>
|
||||||
|
<entry>12 bytes</entry>
|
||||||
|
<entry><acronym>SQL92</acronym> type</entry>
|
||||||
|
<entry>equivalent to timespan</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>reltime</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>original time interval</entry>
|
||||||
|
<entry>limited range, low precision</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>time</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry><acronym>SQL92</acronym> type</entry>
|
||||||
|
<entry>wide range</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>timespan</entry>
|
||||||
|
<entry>12 bytes</entry>
|
||||||
|
<entry>best general time interval</entry>
|
||||||
|
<entry>wide range, high precision</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>timestamp</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry><acronym>SQL92</acronym> type</entry>
|
||||||
|
<entry>limited range</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
|
||||||
<para>
|
<type>timestamp</type> is currently implemented separately from
|
||||||
<table tocentry="1">
|
<type>datetime</type>, although they share input and output routines.
|
||||||
<title><productname>Postgres</productname> Date/Time Ranges</title>
|
</para>
|
||||||
<titleabbrev>Ranges</titleabbrev>
|
|
||||||
<tgroup cols="4">
|
|
||||||
<thead>
|
|
||||||
<row>
|
|
||||||
<entry>Date/Time Type</entry>
|
|
||||||
<entry>Earliest</entry>
|
|
||||||
<entry>Latest</entry>
|
|
||||||
<entry>Resolution</entry>
|
|
||||||
</row>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<row>
|
|
||||||
<entry>abstime</entry>
|
|
||||||
<entry>1901-12-14</entry>
|
|
||||||
<entry>2038-01-19</entry>
|
|
||||||
<entry>1 sec</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>date</entry>
|
|
||||||
<entry>4713 BC</entry>
|
|
||||||
<entry>32767 AD</entry>
|
|
||||||
<entry>1 day</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>datetime</entry>
|
|
||||||
<entry>4713 BC</entry>
|
|
||||||
<entry>1465001 AD</entry>
|
|
||||||
<entry>1 microsec to 14 digits</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>interval</entry>
|
|
||||||
<entry>-178000000 years</entry>
|
|
||||||
<entry>178000000 years</entry>
|
|
||||||
<entry>1 microsec</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>reltime</entry>
|
|
||||||
<entry>-68 years</entry>
|
|
||||||
<entry>+68 years</entry>
|
|
||||||
<entry>1 sec</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>time</entry>
|
|
||||||
<entry>00:00:00.00</entry>
|
|
||||||
<entry>23:59:59.99</entry>
|
|
||||||
<entry>1 microsec</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>timespan</entry>
|
|
||||||
<entry>-178000000 years</entry>
|
|
||||||
<entry>178000000 years</entry>
|
|
||||||
<entry>1 microsec (14 digits)</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>timestamp</entry>
|
|
||||||
<entry>1901-12-14</entry>
|
|
||||||
<entry>2038-01-19</entry>
|
|
||||||
<entry>1 sec</entry>
|
|
||||||
</row>
|
|
||||||
</tbody>
|
|
||||||
</tgroup>
|
|
||||||
</table>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<productname>Postgres</productname> endeavors to be compatible with
|
<table tocentry="1">
|
||||||
<acronym>SQL92</acronym> definitions for typical usage.
|
<title><productname>Postgres</productname> Date/Time Ranges</title>
|
||||||
The <acronym>SQL92</acronym> standard has an odd mix of date and
|
<titleabbrev>Ranges</titleabbrev>
|
||||||
time types and capabilities. Two obvious problems are:
|
<tgroup cols="4">
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>Date/Time Type</entry>
|
||||||
|
<entry>Earliest</entry>
|
||||||
|
<entry>Latest</entry>
|
||||||
|
<entry>Resolution</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>abstime</entry>
|
||||||
|
<entry>1901-12-14</entry>
|
||||||
|
<entry>2038-01-19</entry>
|
||||||
|
<entry>1 sec</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>date</entry>
|
||||||
|
<entry>4713 BC</entry>
|
||||||
|
<entry>32767 AD</entry>
|
||||||
|
<entry>1 day</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>datetime</entry>
|
||||||
|
<entry>4713 BC</entry>
|
||||||
|
<entry>1465001 AD</entry>
|
||||||
|
<entry>1 microsec to 14 digits</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>interval</entry>
|
||||||
|
<entry>-178000000 years</entry>
|
||||||
|
<entry>178000000 years</entry>
|
||||||
|
<entry>1 microsec</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>reltime</entry>
|
||||||
|
<entry>-68 years</entry>
|
||||||
|
<entry>+68 years</entry>
|
||||||
|
<entry>1 sec</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>time</entry>
|
||||||
|
<entry>00:00:00.00</entry>
|
||||||
|
<entry>23:59:59.99</entry>
|
||||||
|
<entry>1 microsec</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>timespan</entry>
|
||||||
|
<entry>-178000000 years</entry>
|
||||||
|
<entry>178000000 years</entry>
|
||||||
|
<entry>1 microsec (14 digits)</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>timestamp</entry>
|
||||||
|
<entry>1901-12-14</entry>
|
||||||
|
<entry>2038-01-19</entry>
|
||||||
|
<entry>1 sec</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
</para>
|
||||||
|
|
||||||
<itemizedlist>
|
<sect2>
|
||||||
<listitem>
|
<title>SQL92 Conventions</title>
|
||||||
<para>
|
|
||||||
Although the <type>date</type> type
|
|
||||||
does not have an associated time zone, the
|
|
||||||
<type>time</type> type can or does.</para></listitem>
|
|
||||||
|
|
||||||
<listitem>
|
<para>
|
||||||
<para>
|
<productname>Postgres</productname> endeavors to be compatible with
|
||||||
The default time zone is specified as a constant integer offset
|
<acronym>SQL92</acronym> definitions for typical usage.
|
||||||
from GMT/UTC.</para></listitem>
|
However, the <acronym>SQL92</acronym> standard has an odd mix of date and
|
||||||
|
time types and capabilities. Two obvious problems are:
|
||||||
|
|
||||||
</itemizedlist>
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Although the <type>date</type> type
|
||||||
|
does not have an associated time zone, the
|
||||||
|
<type>time</type> type can or does.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
However, time zones in the real world can have no meaning unless
|
<listitem>
|
||||||
associated with a date as well as a time
|
<para>
|
||||||
since the offset may vary through the year with daylight savings
|
The default time zone is specified as a constant integer offset
|
||||||
time boundaries.
|
from GMT/UTC.
|
||||||
</para>
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
<para>
|
</itemizedlist>
|
||||||
To address these difficulties, <productname>Postgres</productname>
|
|
||||||
associates time zones only with date and time
|
|
||||||
types which contain both date and time,
|
|
||||||
and assumes local time for any type containing only
|
|
||||||
date or time. Further, time zone support is derived from
|
|
||||||
the underlying operating system
|
|
||||||
time zone capabilities, and hence can handle daylight savings time
|
|
||||||
and other expected behavior.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
Time zones in the real world can have no meaning unless
|
||||||
In future releases, the number of date/time types will decrease,
|
associated with a date as well as a time
|
||||||
with the current implementation of
|
since the offset may vary through the year with daylight savings
|
||||||
<type>datetime</type> becoming <type>timestamp</type>,
|
time boundaries.
|
||||||
<type>timespan</type> becoming <type>interval</type>,
|
</para>
|
||||||
and (possibly) <type>abstime</type> and <type>reltime</type>
|
|
||||||
being deprecated in favor of <type>timestamp</type> and <type>interval</type>.
|
<para>
|
||||||
The more arcane features of the date/time definitions from
|
To address these difficulties, <productname>Postgres</productname>
|
||||||
the <acronym>SQL92</acronym> standard are not likely to be pursued.
|
associates time zones only with date and time
|
||||||
</para>
|
types which contain both date and time,
|
||||||
|
and assumes local time for any type containing only
|
||||||
|
date or time. Further, time zone support is derived from
|
||||||
|
the underlying operating system
|
||||||
|
time zone capabilities, and hence can handle daylight savings time
|
||||||
|
and other expected behavior.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In future releases, the number of date/time types will decrease,
|
||||||
|
with the current implementation of
|
||||||
|
<type>datetime</type> becoming <type>timestamp</type>,
|
||||||
|
<type>timespan</type> becoming <type>interval</type>,
|
||||||
|
and (possibly) <type>abstime</type> and <type>reltime</type>
|
||||||
|
being deprecated in favor of <type>timestamp</type> and <type>interval</type>.
|
||||||
|
The more arcane features of the date/time definitions from
|
||||||
|
the <acronym>SQL92</acronym> standard are not likely to be pursued.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Date/Time Styles</title>
|
<title>Date/Time Styles</title>
|
||||||
@ -840,46 +852,71 @@ which alleviates date specification ambiguities and Y2K collation problems.
|
|||||||
|
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Time Zones</title>
|
<title>Calendar</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<productname>Postgres</productname> obtains time zone support
|
<productname>Postgres</productname> uses Julian dates
|
||||||
from the underlying operating system.
|
for all date/time calculations. They have the nice property of correctly
|
||||||
All dates and times are stored internally in Universal Coordinated Time (UTC),
|
predicting/calculating any date more recent than something like 4013BC
|
||||||
alternately known as Greenwich Mean Time (GMT).
|
to far into the future, using the assumption that the length of the
|
||||||
Times are converted to local time on the database server before being
|
year is 365.2425 days.
|
||||||
sent to the client frontend, hence by default are in the server time zone.</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are several ways to affect the time zone behavior:
|
Date conventions before the 19th century make for interesting reading,
|
||||||
|
but are not consistant enough to warrant coding into a date/time handler.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<itemizedlist spacing="compact" mark="bullet">
|
<sect2>
|
||||||
<listitem>
|
<title>Time Zones</title>
|
||||||
<para>
|
|
||||||
The TZ environment variable used by the backend directly
|
|
||||||
on postmaster startup as the default time zone.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The PGTZ environment variable set at the client used by libpq
|
|
||||||
to send time zone information to the backend upon connection.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The <acronym>SQL</acronym> command <command>SET TIME ZONE</command>
|
|
||||||
sets the time zone for the session.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist></para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If an invalid time zone is specified,
|
<productname>Postgres</productname> obtains time zone support
|
||||||
the time zone becomes GMT (on most systems anyway).
|
from the underlying operating system for dates between 1902 and
|
||||||
</para>
|
2038 (near the typical date limits for Unix-style
|
||||||
</sect2>
|
systems). Outside of this range, all dates are assumed to be
|
||||||
|
specified and used in Universal Coordinated Time (UTC).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
All dates and times are stored internally in Universal UTC,
|
||||||
|
alternately known as Greenwich Mean Time (GMT).
|
||||||
|
Times are converted to local time on the database server before being
|
||||||
|
sent to the client frontend, hence by default are in the server
|
||||||
|
time zone.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There are several ways to affect the time zone behavior:
|
||||||
|
|
||||||
|
<itemizedlist spacing="compact" mark="bullet">
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The TZ environment variable used by the backend directly
|
||||||
|
on postmaster startup as the default time zone.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The PGTZ environment variable set at the client used by libpq
|
||||||
|
to send time zone information to the backend upon connection.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <acronym>SQL</acronym> command <command>SET TIME ZONE</command>
|
||||||
|
sets the time zone for the session.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist></para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If an invalid time zone is specified,
|
||||||
|
the time zone becomes GMT (on most systems anyway).
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Date/Time Input</title>
|
<title>Date/Time Input</title>
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user