Skip to content

P
Postgres FD Implementation
Commit 1def28ff authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Include specific info on available timezones. 

Document date/time input parsing procedure.
parent 2289b403
Show whitespace changes
Inline Side-by-side
Showing with 273 additions and 236 deletions
doc/src/sgml/datatype.sgml
View file @ 1def28ff
......@@ -516,44 +516,48 @@ This is set at compile time and may change in a future release.
</sect1>
<sect1>
<title>Date/Time Types</title>
<sect1>
<title>Date/Time Types</title>
<para>
There are two fundamental kinds of date and time measurements:
<para>
There are two fundamental kinds of date and time measurements
provided by <productname>Postgres</productname>:
absolute clock times and relative time intervals.
Both kinds of quantities should have behaviors demonstrating both
continuity and smoothness.
<productname>Postgres</productname> supplies two primary user-oriented
date and time types,
<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>
Both kinds of time measurements should demonstrate both
continuity and smoothness.
</para>
<para>
In a future release, <type>datetime</type> and <type>timespan</type> are likely
to merge with the <acronym>SQL92</acronym> types <type>timestamp</type>,
<type>interval</type>.
Other date and time types are also available, mostly
for historical reasons.
</para>
<para>
<productname>Postgres</productname> supplies two primary user-oriented
date and time types,
<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>
<table tocentry="1">
<title><productname>Postgres</productname> Date/Time Types</title>
<titleabbrev>Date/Time</titleabbrev>
<tgroup cols="4">
<thead>
<para>
In a future release, <type>datetime</type> and <type>timespan</type> are likely
to merge with the <acronym>SQL92</acronym> types <type>timestamp</type>,
<type>interval</type>.
Other date and time types are also available, mostly
for historical reasons.
</para>
<para>
<table tocentry="1">
<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>
</thead>
<tbody>
<row>
<entry>abstime</entry>
<entry>4 bytes</entry>
......@@ -602,28 +606,28 @@ for historical reasons.
<entry><acronym>SQL92</acronym> type</entry>
<entry>limited range</entry>
</row>
</tbody>
</tgroup>
</table>
</tbody>
</tgroup>
</table>
<type>timestamp</type> is currently implemented separately from
<type>datetime</type>, although they share input and output routines.
</para>
<type>timestamp</type> is currently implemented separately from
<type>datetime</type>, although they share input and output routines.
</para>
<para>
<table tocentry="1">
<title><productname>Postgres</productname> Date/Time Ranges</title>
<titleabbrev>Ranges</titleabbrev>
<tgroup cols="4">
<thead>
<para>
<table tocentry="1">
<title><productname>Postgres</productname> Date/Time Ranges</title>
<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>
</thead>
<tbody>
<row>
<entry>abstime</entry>
<entry>1901-12-14</entry>
......@@ -672,58 +676,66 @@ for historical reasons.
<entry>2038-01-19</entry>
<entry>1 sec</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</tbody>
</tgroup>
</table>
</para>
<para>
<productname>Postgres</productname> endeavors to be compatible with
<acronym>SQL92</acronym> definitions for typical usage.
The <acronym>SQL92</acronym> standard has an odd mix of date and
time types and capabilities. Two obvious problems are:
<sect2>
<title>SQL92 Conventions</title>
<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>
<para>
<productname>Postgres</productname> endeavors to be compatible with
<acronym>SQL92</acronym> definitions for typical usage.
However, the <acronym>SQL92</acronym> standard has an odd mix of date and
time types and capabilities. Two obvious problems are:
<listitem>
<para>
The default time zone is specified as a constant integer offset
from GMT/UTC.</para></listitem>
<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>
</itemizedlist>
<listitem>
<para>
The default time zone is specified as a constant integer offset
from GMT/UTC.
</para>
</listitem>
However, time zones in the real world can have no meaning unless
associated with a date as well as a time
since the offset may vary through the year with daylight savings
time boundaries.
</para>
</itemizedlist>
<para>
To address these difficulties, <productname>Postgres</productname>
associates time zones only with date and time
types which contain both date and time,
Time zones in the real world can have no meaning unless
associated with a date as well as a time
since the offset may vary through the year with daylight savings
time boundaries.
</para>
<para>
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>
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>
<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>
<title>Date/Time Styles</title>
......@@ -840,46 +852,71 @@ which alleviates date specification ambiguities and Y2K collation problems.
</sect2>
<sect2>
<title>Time Zones</title>
<sect2>
<title>Calendar</title>
<para>
<productname>Postgres</productname> obtains time zone support
from the underlying operating system.
All dates and times are stored internally in Universal Coordinated Time (UTC),
<para>
<productname>Postgres</productname> uses Julian dates
for all date/time calculations. They have the nice property of correctly
predicting/calculating any date more recent than something like 4013BC
to far into the future, using the assumption that the length of the
year is 365.2425 days.
</para>
<para>
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>
<sect2>
<title>Time Zones</title>
<para>
<productname>Postgres</productname> obtains time zone support
from the underlying operating system for dates between 1902 and
2038 (near the typical date limits for Unix-style
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>
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:
<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
<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>
</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,
the time zone becomes GMT (on most systems anyway).
</para>
</sect2>
the time zone becomes GMT (on most systems anyway).
</para>
</sect2>
<sect2>
<title>Date/Time Input</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment