rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add information on new timestamp and timestamptz data types. 

Start chapter on recovery techniques. Still needs work for release.
This commit is contained in:
Thomas G. Lockhart 2001-09-28 08:15:35 +00:00
parent 6f58115ddd
commit f9681968e0
5 changed files with 316 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
doc/src/sgml/datatype.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.63 2001/09/13 15:55:22 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.64 2001/09/28 08:15:35 thomas Exp $
--> -->
<chapter id="datatype"> <chapter id="datatype">
@ -229,13 +229,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.63 2001/09/13 15:55:22 pe
<row> <row>
<entry><type>time with time zone</type></entry> <entry><type>time with time zone</type></entry>
<entry></entry> <entry>timetz</entry>
<entry>time of day, including time zone</entry> <entry>time of day, including time zone</entry>
</row> </row>
<row>
<entry><type>timestamp without time zone</type></entry>
<entry>timestamp</entry>
<entry>date and time</entry>
</row>
<row> <row>
<entry><type>timestamp [ with time zone ]</type></entry> <entry><type>timestamp [ with time zone ]</type></entry>
<entry></entry> <entry>timestamptz</entry>
<entry>date and time</entry> <entry>date and time</entry>
</row> </row>
</tbody> </tbody>
@ -981,7 +987,7 @@ SELECT b, char_length(b) FROM test2;
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry><type>timestamp</type></entry> <entry><type>timestamp without time zone</type></entry>
<entry>both date and time</entry> <entry>both date and time</entry>
<entry>8 bytes</entry> <entry>8 bytes</entry>
<entry>4713 BC</entry> <entry>4713 BC</entry>
@ -990,10 +996,10 @@ SELECT b, char_length(b) FROM test2;
</row> </row>
<row> <row>
<entry><type>timestamp [ with time zone ]</type></entry> <entry><type>timestamp [ with time zone ]</type></entry>
<entry>date and time with time zone</entry> <entry>both date and time</entry>
<entry>8 bytes</entry> <entry>8 bytes</entry>
<entry>1903 AD</entry> <entry>4713 BC</entry>
<entry>2037 AD</entry> <entry>AD 1465001</entry>
<entry>1 microsecond / 14 digits</entry> <entry>1 microsecond / 14 digits</entry>
</row> </row>
<row> <row>
@ -1034,21 +1040,37 @@ SELECT b, char_length(b) FROM test2;
<note> <note>
<para> <para>
To ensure compatibility to earlier versions of <productname>Postgres</productname> Time zones, and time zone conventions, are influenced by
we also continue to provide <type>datetime</type> (equivalent to <type>timestamp</type>) and political conventions, not just physical effects. Time zones have
<type>timespan</type> (equivalent to <type>interval</type>), become somewhat standardized during the 1900's, but continue to
however support for these is now restricted to having an be prone to arbitrary changes with time.
implicit translation to <type>timestamp</type> and <productname>PostgreSQL</productname> uses your operating
<type>interval</type>. system's underlying features to provide time zone
The types <type>abstime</type> support, and these systems usually contain information for only
and <type>reltime</type> are lower precision types which are used internally. the time period 1902 through 2038 (corresponding to the full
You are discouraged from using any of these types in new range of conventional Unix system time).
applications and are encouraged to move any old <type>timestamp with time zone</type> will use time zone
ones over when appropriate. Any or all of these internal types might disappear in a future release. information only within that year range, and assumes that times
are in UTC outside that range.
</para> </para>
</note> </note>
</para> </para>
<para>
To ensure compatibility to earlier versions of <productname>Postgres</productname>
we also continue to provide <type>datetime</type>
(equivalent to <type>timestamp</type>) and
<type>timespan</type> (equivalent to <type>interval</type>),
however support for these is now restricted to having an
implicit translation to <type>timestamp</type> and
<type>interval</type>.
The types <type>abstime</type>
and <type>reltime</type> are lower precision types which are used internally.
You are discouraged from using any of these types in new
applications and are encouraged to move any old
ones over when appropriate. Any or all of these internal types
might disappear in a future release.
</para>
<sect2 id="datatype-datetime-input"> <sect2 id="datatype-datetime-input">
<title>Date/Time Input</title> <title>Date/Time Input</title>
@ -1266,6 +1288,10 @@ SELECT b, char_length(b) FROM test2;
<primary>time</primary> <primary>time</primary>
<secondary>data type</secondary> <secondary>data type</secondary>
</indexterm> </indexterm>
<indexterm>
<primary>time without time zone</primary>
<secondary>time</secondary>
</indexterm>
<para> <para>
Per SQL99, this type can be referenced as <type>time</type> and Per SQL99, this type can be referenced as <type>time</type> and
@ -1330,11 +1356,21 @@ SELECT b, char_length(b) FROM test2;
<sect3> <sect3>
<title><type>time with time zone</type></title> <title><type>time with time zone</type></title>
<indexterm>
<primary>time with time zone</primary>
<secondary>data type</secondary>
</indexterm>
<indexterm>
<primary>time</primary>
<secondary>data type</secondary>
</indexterm>
<para> <para>
This type is defined by SQL92, but the definition exhibits This type is defined by SQL92, but the definition exhibits
fundamental deficiencies that render the type nearly useless. In properties which lead to questionable usefulness. In
most cases, a combination of <type>date</type>, most cases, a combination of <type>date</type>,
<type>time</type>, and <type>timestamp</type> <type>time</type>, <type>timestamp without time zone</type>
and <type>timestamp with time zone</type>
should provide a complete range of date/time functionality should provide a complete range of date/time functionality
required by any application. required by any application.
</para> </para>
@ -1382,7 +1418,44 @@ SELECT b, char_length(b) FROM test2;
</sect3> </sect3>
<sect3> <sect3>
<title><type>timestamp</type></title> <title><type>timestamp without time zone</type></title>
<indexterm>
<primary>timestamp without time zone</primary>
<secondary>data type</secondary>
</indexterm>
<para>
Valid input for the <type>timestamp without time zone</type>
type consists of a concatenation
of a date and a time, followed by an optional <literal>AD</literal> or
<literal>BC</literal>, followed by an optional time zone. (See below.)
Thus
<programlisting>
1999-01-08 04:05:06
</programlisting>
is a valid <type>timestamp without time zone</type> value that
is <acronym>ISO</acronym>-compliant.
In addition, the wide-spread format
<programlisting>
January 8 04:05:06 1999 PST
</programlisting>
is supported.
</para>
<para>
For <type>timestamp without time zone</type>, any explicit time
zone specified in the input is silently swallowed. That is, the
resulting date/time value is derived from the explicit date/time
fields in the input value, and is not adjusted for time zone.
</para>
</sect3>
<sect3>
<title><type>timestamp with time zone</type></title>
<indexterm> <indexterm>
<primary>timestamp</primary> <primary>timestamp</primary>
@ -1500,10 +1573,12 @@ January 8 04:05:06 1999 PST
</row> </row>
</thead> </thead>
<tbody> <tbody>
<!--
<row> <row>
<entry>current</entry> <entry>current</entry>
<entry>Current transaction time, deferred</entry> <entry>Current transaction time, deferred</entry>
</row> </row>
-->
<row> <row>
<entry>epoch</entry> <entry>epoch</entry>
<entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry> <entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>

4
doc/src/sgml/datetime.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.21 2001/09/13 15:55:22 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.22 2001/09/28 08:15:35 thomas Exp $
Date/time details Date/time details
--> -->
@ -14,7 +14,7 @@ Date/time details
</indexterm> </indexterm>
<para> <para>
<productname>Postgres</productname> must have internal tabular <productname>Postgres</productname> contains internal tabular
information for time zone decoding, since there is no *nix standard information for time zone decoding, since there is no *nix standard
system interface to provide access to general, cross-timezone system interface to provide access to general, cross-timezone
information. The underlying OS <emphasis>is</emphasis> used to information. The underlying OS <emphasis>is</emphasis> used to

114
doc/src/sgml/func.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.73 2001/09/20 16:41:26 petere Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.74 2001/09/28 08:15:35 thomas Exp $ -->
<chapter id="functions"> <chapter id="functions">
<title>Functions and Operators</title> <title>Functions and Operators</title>
@ -26,10 +26,9 @@
the functions and operators described in this chapter, with the the functions and operators described in this chapter, with the
exception of the most trivial arithmetic and comparison operators exception of the most trivial arithmetic and comparison operators
and some explicitly marked functions, are not specified by the <acronym>SQL</acronym> and some explicitly marked functions, are not specified by the <acronym>SQL</acronym>
standard. However, many other <acronym>RDBMS</acronym> packages provide a lot of the standard. Some of this extended functionality is present in other
same or similar functions, and some of the ones provided in <acronym>RDBMS</acronym> products, and in many cases this
<productname>Postgres</productname> have in fact been inspired by functionality is compatible and consistant between various products.
other implementations.
</para> </para>
@ -302,8 +301,16 @@
<sect1 id="functions-math"> <sect1 id="functions-math">
<title>Mathematical Functions and Operators</title> <title>Mathematical Functions and Operators</title>
<para>
Mathematical operators are provided for many
<productname>PostgreSQL</productname> types. For types without
common mathematical conventions for all possible permutations
(e.g. date/time types) we
describe the actual behavior in subsequent sections.
</para>
<table> <table>
<title>Mathematical Operators</TITLE> <title>Mathematical Operators</title>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
@ -1542,7 +1549,7 @@
<sect1 id="functions-formatting"> <sect1 id="functions-formatting">
<title>Formatting Functions</title> <title>Multi-type Formatting Functions</title>
<indexterm zone="functions-formatting"> <indexterm zone="functions-formatting">
<primary>formatting</primary> <primary>formatting</primary>
@ -2252,18 +2259,99 @@
<sect1 id="functions-datetime"> <sect1 id="functions-datetime">
<title>Date/Time Functions</title> <title>Date/Time Functions and Operators</title>
<para> <para>
<xref linkend="functions-datetime-table"> shows the available <xref linkend="functions-datetime-table"> shows the available
functions for date/time value processing. The basic arithmetic functions for date/time value processing.
operators (<literal>+</literal>, <literal>*</literal>, etc.) are <xref linkend="operators-datetime-table"> illustrates the
also available. For formatting functions, refer to <xref behaviors of the basic arithmetic
operators (<literal>+</literal>, <literal>*</literal>, etc.).
For formatting functions, refer to <xref
linkend="functions-formatting">. You should be familiar with the linkend="functions-formatting">. You should be familiar with the
background information on date/time data types (see <xref background information on date/time data types (see <xref
linkend="datatype-datetime">). linkend="datatype-datetime">).
</para> </para>
<para>
The date/time operators described below behave similarly for types
involving time zones as well as those without.
<table id="operators-datetime-table">
<title>Date/Time Operators</title>
<tgroup cols="4">
<thead>
<row>
<entry>Name</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry> <type><literal>+</literal> </entry>
<entry><type>timestamp</type> '2001-09-28 01:00' + <type>interval</type> '23 hours'</entry>
<entry><type>timestamp</type> '2001-09-29 00:00'</entry>
</row>
<row>
<entry> <type><literal>+</literal> </entry>
<entry><type>date</type> '2001-09-28' + <type>interval</type> '1 hour'</entry>
<entry><type>timestamp</type> '2001-09-28 01:00'</entry>
</row>
<row>
<entry> <type><literal>+</literal> </entry>
<entry><type>time</type> '01:00' + <type>interval</type> '3 hours'</entry>
<entry><type>time</type> '04:00'</entry>
</row>
<row>
<entry> <type><literal>-</literal> </entry>
<entry><type>timestamp</type> '2001-09-28 23:00' - <type>interval</type> '23 hours'</entry>
<entry><type>timestamp</type> '2001-09-28'</entry>
</row>
<row>
<entry> <type><literal>-</literal> </entry>
<entry><type>date</type> '2001-09-28' + <type>interval</type> '1 hour'</entry>
<entry><type>timestamp</type> '2001-09-27 23:00'</entry>
</row>
<row>
<entry> <type><literal>-</literal> </entry>
<entry><type>time</type> '05:00' + <type>interval</type> '2 hours'</entry>
<entry><type>time</type> '03:00'</entry>
</row>
<row>
<entry> <type><literal>-</literal> </entry>
<entry><type>interval</type> '2 hours' - <type>time</type> '05:00'</entry>
<entry><type>time</type> '03:00:00'</entry>
</row>
<row>
<entry> <literal>*</literal> </entry>
<entry><type>interval</type> '1 hour' * <type>int</type> '3'</entry>
<entry><type>interval</type> '03:00'</entry>
</row>
<row>
<entry> <literal>/</literal> </entry>
<entry><type>interval</type> '1 hour' / <type>int</type> '3'</entry>
<entry><type>interval</type> '00:20'</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The date/time functions are summarized below, with additional
details in subsequent sections.
<table id="functions-datetime-table"> <table id="functions-datetime-table">
<title>Date/Time Functions</title> <title>Date/Time Functions</title>
<tgroup cols="4"> <tgroup cols="4">
@ -2431,7 +2519,7 @@
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
<sect2 id="functions-datetime-extract"> <sect2 id="functions-datetime-extract">
<title><function>EXTRACT</function>, <function>date_part</function></title> <title><function>EXTRACT</function>, <function>date_part</function></title>
@ -2546,7 +2634,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
<listitem> <listitem>
<para> <para>
For <type>date</type> and <type>timestamp</type> values, the For <type>date</type> and <type>timestamp</type> values, the
number of seconds since 1970-01-01 00:00:00 (Result may be number of seconds since 1970-01-01 00:00:00-00 (Result may be
negative.); for <type>interval</type> values, the total number negative.); for <type>interval</type> values, the total number
of seconds in the interval of seconds in the interval
</para> </para>

4
doc/src/sgml/manage.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.16 2001/09/13 15:55:23 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.17 2001/09/28 08:15:35 thomas Exp $
--> -->
<Chapter Id="manage"> <Chapter Id="manage">
@ -31,7 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.16 2001/09/13 15:55:2
<Title>Database Creation</Title> <Title>Database Creation</Title>
<Para> <Para>
Databases are created by the <Command>create database</Command> issued from Databases are created by the <Command>CREATE DATABASE</Command> issued from
within <ProductName>Postgres</ProductName>. <Application>createdb</Application> is a command-line within <ProductName>Postgres</ProductName>. <Application>createdb</Application> is a command-line
utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>. utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>.
</Para> </Para>

121
doc/src/sgml/recovery.sgml
View File

@ -1,8 +1,117 @@
<Chapter Id="recovery"> <chapter Id="failure">
<Title>Database Recovery</Title> <title>Database Failures</title>
<Para> <para>
This section needs to be written. Volunteers? Database failures (or the possibility of such) must be assumed to be
</Para> lurking, ready to strike at some time in the future. A prudent
database administrator will plan for the inevitability of failures
of all possible kinds, and will have appropriate plans and
procedures in place <emphasis>before</emphasis> the failure occurs.
</para>
</Chapter> <para>
Database recovery is necessary in the event of hardware or software
failure. There are several categories of failures; some of these
require relatively minor adjustments to the database, while others
may depend on the existance of previously prepared database dumps
and other recovery data sets. It should be emphasized that if your
data is important and/or difficult to regenerate, then you should
have considered and prepared for various failure scenarios.
</para>
<sect1>
<title>Disk Filled</title>
<para>
A filled data disk may result in subsequent corruption of database
indices, but not of the fundamental data tables. If the WAL files
are on the same disk (as is the case for a default configuration)
then a filled disk during database initialization may result in
corrupted or incomplete WAL files. This failure condition is
detected and the database will refuse to start up. You must free
up additional space on the disk (or move the WAL area to another
disk; see <xref id=xxx></xref>) and then restart the
<application>postmaster</application> to recover from this condition.
</para>
</sect1>
<sect1>
<title>Disk Failed</title>
<para>
Failure of any disk (or of a logical storage device such as a RAID
subsystem) involved with an active database will require
that the database be recovered from a previously prepared database
dump. This dump must be prepared using
<application>pg_dumpall</application>, and updates to the database
occuring after the database installation was dumped will be lost.
</para>
</sect1>
<sect1>
<title>File Corrupted</title>
<para>
</para>
</sect1>
<sect1>
<title>Table Corrupted</title>
<para>
</para>
</sect1>
<sect1>
<title></title>
<para>
</para>
</sect1>
<sect1>
<title></title>
<para>
</para>
</sect1>
<sect1>
<title></title>
<para>
</para>
</sect1>
</chapter>
<chapter Id="recovery">
<title>Database Recovery</title>
<para>
Database recovery is necessary in the event of hardware or software
failure. There are several categories of failures; some of these
require relatively minor adjustments to the database, while others
may depend on the existance of previously prepared database dumps
and other recovery data sets. It should be emphasized that if your
data is important and/or difficult to regenerate, then you should
have considered and prepared for various failure scenarios.
</para>
<sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: ("postgres.sgml" "set" "book" "chapter")
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-ecat-files:nil
End:
-->