Start chapter on recovery techniques. Still needs work for release.
<!--
-$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">
<row>
<entry><type>time with time zone</type></entry>
- <entry></entry>
+ <entry>timetz</entry>
<entry>time of day, including time zone</entry>
</row>
<row>
+ <entry><type>timestamp without time zone</type></entry>
+ <entry>timestamp</entry>
+ <entry>date and time</entry>
+ </row>
+
+ <row>
<entry><type>timestamp [ with time zone ]</type></entry>
- <entry></entry>
+ <entry>timestamptz</entry>
<entry>date and time</entry>
</row>
</tbody>
</thead>
<tbody>
<row>
- <entry><type>timestamp</type></entry>
+ <entry><type>timestamp without time zone</type></entry>
<entry>both date and time</entry>
<entry>8 bytes</entry>
<entry>4713 BC</entry>
</row>
<row>
<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>1903 AD</entry>
- <entry>2037 AD</entry>
+ <entry>4713 BC</entry>
+ <entry>AD 1465001</entry>
<entry>1 microsecond / 14 digits</entry>
</row>
<row>
<note>
<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.
+ Time zones, and time zone conventions, are influenced by
+ political conventions, not just physical effects. Time zones have
+ become somewhat standardized during the 1900's, but continue to
+ be prone to arbitrary changes with time.
+ <productname>PostgreSQL</productname> uses your operating
+ system's underlying features to provide time zone
+ support, and these systems usually contain information for only
+ the time period 1902 through 2038 (corresponding to the full
+ range of conventional Unix system time).
+ <type>timestamp with time zone</type> will use time zone
+ information only within that year range, and assumes that times
+ are in UTC outside that range.
</para>
</note>
</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">
<title>Date/Time Input</title>
<primary>time</primary>
<secondary>data type</secondary>
</indexterm>
+ <indexterm>
+ <primary>time without time zone</primary>
+ <secondary>time</secondary>
+ </indexterm>
<para>
Per SQL99, this type can be referenced as <type>time</type> and
<sect3>
<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>
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>,
- <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
required by any application.
</para>
</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>
<primary>timestamp</primary>
</row>
</thead>
<tbody>
+<!--
<row>
<entry>current</entry>
<entry>Current transaction time, deferred</entry>
</row>
+-->
<row>
<entry>epoch</entry>
<entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>
<!--
-$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
-->
</indexterm>
<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
system interface to provide access to general, cross-timezone
information. The underlying OS <emphasis>is</emphasis> used to
-<!-- $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">
<title>Functions and Operators</title>
the functions and operators described in this chapter, with the
exception of the most trivial arithmetic and comparison operators
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
- same or similar functions, and some of the ones provided in
- <productname>Postgres</productname> have in fact been inspired by
- other implementations.
+ standard. Some of this extended functionality is present in other
+ <acronym>RDBMS</acronym> products, and in many cases this
+ functionality is compatible and consistant between various products.
</para>
<sect1 id="functions-math">
<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>
- <title>Mathematical Operators</TITLE>
+ <title>Mathematical Operators</title>
<tgroup cols="4">
<thead>
<sect1 id="functions-formatting">
- <title>Formatting Functions</title>
+ <title>Multi-type Formatting Functions</title>
<indexterm zone="functions-formatting">
<primary>formatting</primary>
<sect1 id="functions-datetime">
- <title>Date/Time Functions</title>
+ <title>Date/Time Functions and Operators</title>
<para>
<xref linkend="functions-datetime-table"> shows the available
- functions for date/time value processing. The basic arithmetic
- operators (<literal>+</literal>, <literal>*</literal>, etc.) are
- also available. For formatting functions, refer to <xref
+ functions for date/time value processing.
+ <xref linkend="operators-datetime-table"> illustrates the
+ 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
background information on date/time data types (see <xref
linkend="datatype-datetime">).
</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">
<title>Date/Time Functions</title>
<tgroup cols="4">
</tbody>
</tgroup>
</table>
-
+ </para>
<sect2 id="functions-datetime-extract">
<title><function>EXTRACT</function>, <function>date_part</function></title>
<listitem>
<para>
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
of seconds in the interval
</para>
<!--
-$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">
<Title>Database Creation</Title>
<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
utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>.
</Para>
-<Chapter Id="recovery">
-<Title>Database Recovery</Title>
+<chapter Id="failure">
+ <title>Database Failures</title>
-<Para>
-This section needs to be written. Volunteers?
-</Para>
+ <para>
+ Database failures (or the possibility of such) must be assumed to be
+ 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:
+-->