Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit f968196

Browse files
author
Thomas G. Lockhart
committed
Add information on new timestamp and timestamptz data types.
Start chapter on recovery techniques. Still needs work for release.
1 parent 6f58115 commit f968196

File tree

5 files changed

+316
-44
lines changed

5 files changed

+316
-44
lines changed

‎doc/src/sgml/datatype.sgml

Lines changed: 96 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.63 2001/09/13 15:55:22 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.64 2001/09/28 08:15:35 thomas Exp $
33
-->
44

55
<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
229229

230230
<row>
231231
<entry><type>time with time zone</type></entry>
232-
<entry></entry>
232+
<entry>timetz</entry>
233233
<entry>time of day, including time zone</entry>
234234
</row>
235235

236+
<row>
237+
<entry><type>timestamp without time zone</type></entry>
238+
<entry>timestamp</entry>
239+
<entry>date and time</entry>
240+
</row>
241+
236242
<row>
237243
<entry><type>timestamp [ with time zone ]</type></entry>
238-
<entry></entry>
244+
<entry>timestamptz</entry>
239245
<entry>date and time</entry>
240246
</row>
241247
</tbody>
@@ -981,7 +987,7 @@ SELECT b, char_length(b) FROM test2;
981987
</thead>
982988
<tbody>
983989
<row>
984-
<entry><type>timestamp</type></entry>
990+
<entry><type>timestamp without time zone</type></entry>
985991
<entry>both date and time</entry>
986992
<entry>8 bytes</entry>
987993
<entry>4713 BC</entry>
@@ -990,10 +996,10 @@ SELECT b, char_length(b) FROM test2;
990996
</row>
991997
<row>
992998
<entry><type>timestamp [ with time zone ]</type></entry>
993-
<entry>date and time with time zone</entry>
999+
<entry>both date and time</entry>
9941000
<entry>8 bytes</entry>
995-
<entry>1903 AD</entry>
996-
<entry>2037 AD</entry>
1001+
<entry>4713 BC</entry>
1002+
<entry>AD 1465001</entry>
9971003
<entry>1 microsecond / 14 digits</entry>
9981004
</row>
9991005
<row>
@@ -1034,21 +1040,37 @@ SELECT b, char_length(b) FROM test2;
10341040

10351041
<note>
10361042
<para>
1037-
To ensure compatibility to earlier versions of <productname>Postgres</productname>
1038-
we also continue to provide <type>datetime</type> (equivalent to <type>timestamp</type>) and
1039-
<type>timespan</type> (equivalent to <type>interval</type>),
1040-
however support for these is now restricted to having an
1041-
implicit translation to <type>timestamp</type> and
1042-
<type>interval</type>.
1043-
The types <type>abstime</type>
1044-
and <type>reltime</type> are lower precision types which are used internally.
1045-
You are discouraged from using any of these types in new
1046-
applications and are encouraged to move any old
1047-
ones over when appropriate. Any or all of these internal types might disappear in a future release.
1043+
Time zones, and time zone conventions, are influenced by
1044+
political conventions, not just physical effects. Time zones have
1045+
become somewhat standardized during the 1900's, but continue to
1046+
be prone to arbitrary changes with time.
1047+
<productname>PostgreSQL</productname> uses your operating
1048+
system's underlying features to provide time zone
1049+
support, and these systems usually contain information for only
1050+
the time period 1902 through 2038 (corresponding to the full
1051+
range of conventional Unix system time).
1052+
<type>timestamp with time zone</type> will use time zone
1053+
information only within that year range, and assumes that times
1054+
are in UTC outside that range.
10481055
</para>
10491056
</note>
10501057
</para>
10511058

1059+
<para>
1060+
To ensure compatibility to earlier versions of <productname>Postgres</productname>
1061+
we also continue to provide <type>datetime</type>
1062+
(equivalent to <type>timestamp</type>) and
1063+
<type>timespan</type> (equivalent to <type>interval</type>),
1064+
however support for these is now restricted to having an
1065+
implicit translation to <type>timestamp</type> and
1066+
<type>interval</type>.
1067+
The types <type>abstime</type>
1068+
and <type>reltime</type> are lower precision types which are used internally.
1069+
You are discouraged from using any of these types in new
1070+
applications and are encouraged to move any old
1071+
ones over when appropriate. Any or all of these internal types
1072+
might disappear in a future release.
1073+
</para>
10521074

10531075
<sect2 id="datatype-datetime-input">
10541076
<title>Date/Time Input</title>
@@ -1266,6 +1288,10 @@ SELECT b, char_length(b) FROM test2;
12661288
<primary>time</primary>
12671289
<secondary>data type</secondary>
12681290
</indexterm>
1291+
<indexterm>
1292+
<primary>time without time zone</primary>
1293+
<secondary>time</secondary>
1294+
</indexterm>
12691295

12701296
<para>
12711297
Per SQL99, this type can be referenced as <type>time</type> and
@@ -1330,11 +1356,21 @@ SELECT b, char_length(b) FROM test2;
13301356
<sect3>
13311357
<title><type>time with time zone</type></title>
13321358

1359+
<indexterm>
1360+
<primary>time with time zone</primary>
1361+
<secondary>data type</secondary>
1362+
</indexterm>
1363+
<indexterm>
1364+
<primary>time</primary>
1365+
<secondary>data type</secondary>
1366+
</indexterm>
1367+
13331368
<para>
13341369
This type is defined by SQL92, but the definition exhibits
1335-
fundamental deficiencies that render the type nearly useless. In
1370+
properties which lead to questionable usefulness. In
13361371
most cases, a combination of <type>date</type>,
1337-
<type>time</type>, and <type>timestamp</type>
1372+
<type>time</type>, <type>timestamp without time zone</type>
1373+
and <type>timestamp with time zone</type>
13381374
should provide a complete range of date/time functionality
13391375
required by any application.
13401376
</para>
@@ -1382,7 +1418,44 @@ SELECT b, char_length(b) FROM test2;
13821418
</sect3>
13831419

13841420
<sect3>
1385-
<title><type>timestamp</type></title>
1421+
<title><type>timestamp without time zone</type></title>
1422+
1423+
<indexterm>
1424+
<primary>timestamp without time zone</primary>
1425+
<secondary>data type</secondary>
1426+
</indexterm>
1427+
1428+
<para>
1429+
Valid input for the <type>timestamp without time zone</type>
1430+
type consists of a concatenation
1431+
of a date and a time, followed by an optional <literal>AD</literal> or
1432+
<literal>BC</literal>, followed by an optional time zone. (See below.)
1433+
Thus
1434+
1435+
<programlisting>
1436+
1999-01-08 04:05:06
1437+
</programlisting>
1438+
1439+
is a valid <type>timestamp without time zone</type> value that
1440+
is <acronym>ISO</acronym>-compliant.
1441+
In addition, the wide-spread format
1442+
1443+
<programlisting>
1444+
January 8 04:05:06 1999 PST
1445+
</programlisting>
1446+
is supported.
1447+
</para>
1448+
1449+
<para>
1450+
For <type>timestamp without time zone</type>, any explicit time
1451+
zone specified in the input is silently swallowed. That is, the
1452+
resulting date/time value is derived from the explicit date/time
1453+
fields in the input value, and is not adjusted for time zone.
1454+
</para>
1455+
</sect3>
1456+
1457+
<sect3>
1458+
<title><type>timestamp with time zone</type></title>
13861459

13871460
<indexterm>
13881461
<primary>timestamp</primary>
@@ -1500,10 +1573,12 @@ January 8 04:05:06 1999 PST
15001573
</row>
15011574
</thead>
15021575
<tbody>
1576+
<!--
15031577
<row>
15041578
<entry>current</entry>
15051579
<entry>Current transaction time, deferred</entry>
15061580
</row>
1581+
-->
15071582
<row>
15081583
<entry>epoch</entry>
15091584
<entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>

‎doc/src/sgml/datetime.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.21 2001/09/13 15:55:22 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.22 2001/09/28 08:15:35 thomas Exp $
33
Date/time details
44
-->
55

@@ -14,7 +14,7 @@ Date/time details
1414
</indexterm>
1515

1616
<para>
17-
<productname>Postgres</productname> must have internal tabular
17+
<productname>Postgres</productname> contains internal tabular
1818
information for time zone decoding, since there is no *nix standard
1919
system interface to provide access to general, cross-timezone
2020
information. The underlying OS <emphasis>is</emphasis> used to

‎doc/src/sgml/func.sgml

Lines changed: 101 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.73 2001/09/20 16:41:26 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.74 2001/09/28 08:15:35 thomas Exp $ -->
22

33
<chapter id="functions">
44
<title>Functions and Operators</title>
@@ -26,10 +26,9 @@
2626
the functions and operators described in this chapter, with the
2727
exception of the most trivial arithmetic and comparison operators
2828
and some explicitly marked functions, are not specified by the <acronym>SQL</acronym>
29-
standard. However, many other <acronym>RDBMS</acronym> packages provide a lot of the
30-
same or similar functions, and some of the ones provided in
31-
<productname>Postgres</productname> have in fact been inspired by
32-
other implementations.
29+
standard. Some of this extended functionality is present in other
30+
<acronym>RDBMS</acronym> products, and in many cases this
31+
functionality is compatible and consistant between various products.
3332
</para>
3433

3534

@@ -302,8 +301,16 @@
302301
<sect1 id="functions-math">
303302
<title>Mathematical Functions and Operators</title>
304303

304+
<para>
305+
Mathematical operators are provided for many
306+
<productname>PostgreSQL</productname> types. For types without
307+
common mathematical conventions for all possible permutations
308+
(e.g. date/time types) we
309+
describe the actual behavior in subsequent sections.
310+
</para>
311+
305312
<table>
306-
<title>Mathematical Operators</TITLE>
313+
<title>Mathematical Operators</title>
307314

308315
<tgroup cols="4">
309316
<thead>
@@ -1542,7 +1549,7 @@
15421549

15431550

15441551
<sect1 id="functions-formatting">
1545-
<title>Formatting Functions</title>
1552+
<title>Multi-type Formatting Functions</title>
15461553

15471554
<indexterm zone="functions-formatting">
15481555
<primary>formatting</primary>
@@ -2252,18 +2259,99 @@
22522259

22532260

22542261
<sect1 id="functions-datetime">
2255-
<title>Date/Time Functions</title>
2262+
<title>Date/Time Functions and Operators</title>
22562263

22572264
<para>
22582265
<xref linkend="functions-datetime-table"> shows the available
2259-
functions for date/time value processing. The basic arithmetic
2260-
operators (<literal>+</literal>, <literal>*</literal>, etc.) are
2261-
also available. For formatting functions, refer to <xref
2266+
functions for date/time value processing.
2267+
<xref linkend="operators-datetime-table"> illustrates the
2268+
behaviors of the basic arithmetic
2269+
operators (<literal>+</literal>, <literal>*</literal>, etc.).
2270+
For formatting functions, refer to <xref
22622271
linkend="functions-formatting">. You should be familiar with the
22632272
background information on date/time data types (see <xref
22642273
linkend="datatype-datetime">).
22652274
</para>
22662275

2276+
<para>
2277+
The date/time operators described below behave similarly for types
2278+
involving time zones as well as those without.
2279+
2280+
<table id="operators-datetime-table">
2281+
<title>Date/Time Operators</title>
2282+
2283+
<tgroup cols="4">
2284+
<thead>
2285+
<row>
2286+
<entry>Name</entry>
2287+
<entry>Example</entry>
2288+
<entry>Result</entry>
2289+
</row>
2290+
</thead>
2291+
2292+
<tbody>
2293+
<row>
2294+
<entry> <type><literal>+</literal> </entry>
2295+
<entry><type>timestamp</type> '2001-09-28 01:00' + <type>interval</type> '23 hours'</entry>
2296+
<entry><type>timestamp</type> '2001-09-29 00:00'</entry>
2297+
</row>
2298+
2299+
<row>
2300+
<entry> <type><literal>+</literal> </entry>
2301+
<entry><type>date</type> '2001-09-28' + <type>interval</type> '1 hour'</entry>
2302+
<entry><type>timestamp</type> '2001-09-28 01:00'</entry>
2303+
</row>
2304+
2305+
<row>
2306+
<entry> <type><literal>+</literal> </entry>
2307+
<entry><type>time</type> '01:00' + <type>interval</type> '3 hours'</entry>
2308+
<entry><type>time</type> '04:00'</entry>
2309+
</row>
2310+
2311+
<row>
2312+
<entry> <type><literal>-</literal> </entry>
2313+
<entry><type>timestamp</type> '2001-09-28 23:00' - <type>interval</type> '23 hours'</entry>
2314+
<entry><type>timestamp</type> '2001-09-28'</entry>
2315+
</row>
2316+
2317+
<row>
2318+
<entry> <type><literal>-</literal> </entry>
2319+
<entry><type>date</type> '2001-09-28' + <type>interval</type> '1 hour'</entry>
2320+
<entry><type>timestamp</type> '2001-09-27 23:00'</entry>
2321+
</row>
2322+
2323+
<row>
2324+
<entry> <type><literal>-</literal> </entry>
2325+
<entry><type>time</type> '05:00' + <type>interval</type> '2 hours'</entry>
2326+
<entry><type>time</type> '03:00'</entry>
2327+
</row>
2328+
2329+
<row>
2330+
<entry> <type><literal>-</literal> </entry>
2331+
<entry><type>interval</type> '2 hours' - <type>time</type> '05:00'</entry>
2332+
<entry><type>time</type> '03:00:00'</entry>
2333+
</row>
2334+
2335+
<row>
2336+
<entry> <literal>*</literal> </entry>
2337+
<entry><type>interval</type> '1 hour' * <type>int</type> '3'</entry>
2338+
<entry><type>interval</type> '03:00'</entry>
2339+
</row>
2340+
2341+
<row>
2342+
<entry> <literal>/</literal> </entry>
2343+
<entry><type>interval</type> '1 hour' / <type>int</type> '3'</entry>
2344+
<entry><type>interval</type> '00:20'</entry>
2345+
</row>
2346+
</tbody>
2347+
</tgroup>
2348+
</table>
2349+
</para>
2350+
2351+
<para>
2352+
The date/time functions are summarized below, with additional
2353+
details in subsequent sections.
2354+
22672355
<table id="functions-datetime-table">
22682356
<title>Date/Time Functions</title>
22692357
<tgroup cols="4">
@@ -2431,7 +2519,7 @@
24312519
</tbody>
24322520
</tgroup>
24332521
</table>
2434-
2522+
</para>
24352523

24362524
<sect2 id="functions-datetime-extract">
24372525
<title><function>EXTRACT</function>, <function>date_part</function></title>
@@ -2546,7 +2634,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
25462634
<listitem>
25472635
<para>
25482636
For <type>date</type> and <type>timestamp</type> values, the
2549-
number of seconds since 1970-01-01 00:00:00 (Result may be
2637+
number of seconds since 1970-01-01 00:00:00-00 (Result may be
25502638
negative.); for <type>interval</type> values, the total number
25512639
of seconds in the interval
25522640
</para>

‎doc/src/sgml/manage.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.16 2001/09/13 15:55:23 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.17 2001/09/28 08:15:35 thomas Exp $
33
-->
44

55
<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
3131
<Title>Database Creation</Title>
3232

3333
<Para>
34-
Databases are created by the <Command>create database</Command> issued from
34+
Databases are created by the <Command>CREATE DATABASE</Command> issued from
3535
within <ProductName>Postgres</ProductName>. <Application>createdb</Application> is a command-line
3636
utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>.
3737
</Para>

0 commit comments

Comments
 (0)