From f9681968e06a9d6e0c12b2f1e64cf66c486cb54a Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" <lockhart@fourpalms.org> Date: Fri, 28 Sep 2001 08:15:35 +0000 Subject: [PATCH] Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release. --- doc/src/sgml/datatype.sgml | 117 ++++++++++++++++++++++++++++------- doc/src/sgml/datetime.sgml | 4 +- doc/src/sgml/func.sgml | 114 ++++++++++++++++++++++++++++++---- doc/src/sgml/manage.sgml | 4 +- doc/src/sgml/recovery.sgml | 121 +++++++++++++++++++++++++++++++++++-- 5 files changed, 316 insertions(+), 44 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 20863a1532..646639409f 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -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"> @@ -229,13 +229,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.63 2001/09/13 15:55:22 pe <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> @@ -981,7 +987,7 @@ SELECT b, char_length(b) FROM test2; </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> @@ -990,10 +996,10 @@ SELECT b, char_length(b) FROM test2; </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> @@ -1034,21 +1040,37 @@ SELECT b, char_length(b) FROM test2; <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> @@ -1266,6 +1288,10 @@ SELECT b, char_length(b) FROM test2; <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 @@ -1330,11 +1356,21 @@ SELECT b, char_length(b) FROM test2; <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> @@ -1382,7 +1418,44 @@ SELECT b, char_length(b) FROM test2; </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> @@ -1500,10 +1573,12 @@ January 8 04:05:06 1999 PST </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> diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 5fceb8ce7b..23e6c587a6 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -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 --> @@ -14,7 +14,7 @@ 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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0a8b2f6d73..0de8db1538 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -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"> <title>Functions and Operators</title> @@ -26,10 +26,9 @@ 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> @@ -302,8 +301,16 @@ <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> @@ -1542,7 +1549,7 @@ <sect1 id="functions-formatting"> - <title>Formatting Functions</title> + <title>Multi-type Formatting Functions</title> <indexterm zone="functions-formatting"> <primary>formatting</primary> @@ -2252,18 +2259,99 @@ <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"> @@ -2431,7 +2519,7 @@ </tbody> </tgroup> </table> - + </para> <sect2 id="functions-datetime-extract"> <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> <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> diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml index f89e316f90..0b58ddd76b 100644 --- a/doc/src/sgml/manage.sgml +++ b/doc/src/sgml/manage.sgml @@ -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"> @@ -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> <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> diff --git a/doc/src/sgml/recovery.sgml b/doc/src/sgml/recovery.sgml index ba19b6ed6c..e4e74fdfd2 100644 --- a/doc/src/sgml/recovery.sgml +++ b/doc/src/sgml/recovery.sgml @@ -1,8 +1,117 @@ -<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: +--> -- 2.24.1