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. ...@@ -516,44 +516,48 @@ 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
provided by <productname>Postgres</productname>:
absolute clock times and relative time intervals. absolute clock times and relative time intervals.
Both kinds of quantities should have behaviors demonstrating both Both kinds of time measurements should demonstrate both
continuity and smoothness. continuity and smoothness.
<productname>Postgres</productname> supplies two primary user-oriented </para>
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> <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.
</para>
<para>
<table tocentry="1">
<title><productname>Postgres</productname> Date/Time Types</title>
<titleabbrev>Date/Time</titleabbrev>
<tgroup cols="4">
<thead>
<row> <row>
<entry>Date/Time Type</entry> <entry>Date/Time Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Recommendation</entry> <entry>Recommendation</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>abstime</entry> <entry>abstime</entry>
<entry>4 bytes</entry> <entry>4 bytes</entry>
...@@ -602,28 +606,28 @@ for historical reasons. ...@@ -602,28 +606,28 @@ for historical reasons.
<entry><acronym>SQL92</acronym> type</entry> <entry><acronym>SQL92</acronym> type</entry>
<entry>limited range</entry> <entry>limited range</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
<type>timestamp</type> is currently implemented separately from <type>timestamp</type> is currently implemented separately from
<type>datetime</type>, although they share input and output routines. <type>datetime</type>, although they share input and output routines.
</para> </para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Date/Time Ranges</title> <title><productname>Postgres</productname> Date/Time Ranges</title>
<titleabbrev>Ranges</titleabbrev> <titleabbrev>Ranges</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>Date/Time Type</entry> <entry>Date/Time Type</entry>
<entry>Earliest</entry> <entry>Earliest</entry>
<entry>Latest</entry> <entry>Latest</entry>
<entry>Resolution</entry> <entry>Resolution</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>abstime</entry> <entry>abstime</entry>
<entry>1901-12-14</entry> <entry>1901-12-14</entry>
...@@ -672,58 +676,66 @@ for historical reasons. ...@@ -672,58 +676,66 @@ for historical reasons.
<entry>2038-01-19</entry> <entry>2038-01-19</entry>
<entry>1 sec</entry> <entry>1 sec</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <sect2>
<productname>Postgres</productname> endeavors to be compatible with <title>SQL92 Conventions</title>
<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:
<itemizedlist> <para>
<listitem> <productname>Postgres</productname> endeavors to be compatible with
<para> <acronym>SQL92</acronym> definitions for typical usage.
Although the <type>date</type> type However, the <acronym>SQL92</acronym> standard has an odd mix of date and
does not have an associated time zone, the time types and capabilities. Two obvious problems are:
<type>time</type> type can or does.</para></listitem>
<listitem> <itemizedlist>
<para> <listitem>
The default time zone is specified as a constant integer offset <para>
from GMT/UTC.</para></listitem> 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 </itemizedlist>
associated with a date as well as a time
since the offset may vary through the year with daylight savings
time boundaries.
</para>
<para> Time zones in the real world can have no meaning unless
To address these difficulties, <productname>Postgres</productname> associated with a date as well as a time
associates time zones only with date and time since the offset may vary through the year with daylight savings
types which contain both date and time, 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 and assumes local time for any type containing only
date or time. Further, time zone support is derived from date or time. Further, time zone support is derived from
the underlying operating system the underlying operating system
time zone capabilities, and hence can handle daylight savings time time zone capabilities, and hence can handle daylight savings time
and other expected behavior. and other expected behavior.
</para> </para>
<para> <para>
In future releases, the number of date/time types will decrease, In future releases, the number of date/time types will decrease,
with the current implementation of with the current implementation of
<type>datetime</type> becoming <type>timestamp</type>, <type>datetime</type> becoming <type>timestamp</type>,
<type>timespan</type> becoming <type>interval</type>, <type>timespan</type> becoming <type>interval</type>,
and (possibly) <type>abstime</type> and <type>reltime</type> and (possibly) <type>abstime</type> and <type>reltime</type>
being deprecated in favor of <type>timestamp</type> and <type>interval</type>. being deprecated in favor of <type>timestamp</type> and <type>interval</type>.
The more arcane features of the date/time definitions from The more arcane features of the date/time definitions from
the <acronym>SQL92</acronym> standard are not likely to be pursued. the <acronym>SQL92</acronym> standard are not likely to be pursued.
</para> </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. ...@@ -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
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). alternately known as Greenwich Mean Time (GMT).
Times are converted to local time on the database server before being 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> sent to the client frontend, hence by default are in the server
time zone.
</para>
<para> <para>
There are several ways to affect the time zone behavior: There are several ways to affect the time zone behavior:
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
<listitem> <listitem>
<para> <para>
The TZ environment variable used by the backend directly The TZ environment variable used by the backend directly
on postmaster startup as the default time zone. on postmaster startup as the default time zone.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The PGTZ environment variable set at the client used by libpq The PGTZ environment variable set at the client used by libpq
to send time zone information to the backend upon connection. to send time zone information to the backend upon connection.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The <acronym>SQL</acronym> command <command>SET TIME ZONE</command> The <acronym>SQL</acronym> command <command>SET TIME ZONE</command>
sets the time zone for the session. sets the time zone for the session.
</para> </para>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist></para>
<para> <para>
If an invalid time zone is specified, If an invalid time zone is specified,
the time zone becomes GMT (on most systems anyway). the time zone becomes GMT (on most systems anyway).
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Date/Time Input</title> <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