database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-23 03:21:12 +03:00
Code Activity

Add mention of the SERIAL data type.

Browse Source 
Change claim of "no limit" on maximum date for datetime type to
 more realistic 1465001 AD. Thanks Tatsuo for pointing this out :)
Clean up markup.
This commit is contained in:
Thomas G. Lockhart
1998-10-14 16:26:31 +00:00
parent edadec91f7
commit 3103a05c64
1 changed files with 249 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,26 +3,30 @@
<Abstract> <Abstract>
<Para> <Para>
Describes the built-in data types available in <ProductName>Postgres</ProductName>. Describes the built-in data types available in
<ProductName>Postgres</ProductName>.
</Para> </Para>
</Abstract> </Abstract>
<Para> <Para>
<ProductName>Postgres</ProductName> has a rich set of native data types available to users. <ProductName>Postgres</ProductName> has a rich set of native data
types available to users.
Users may add new types to <ProductName>Postgres</ProductName> using the Users may add new types to <ProductName>Postgres</ProductName> using the
<Command>define type</Command> <Command>define type</Command>
command described elsewhere. command described elsewhere.
<Para> <Para>
In the context of data types, the following sections will discuss SQL standards In the context of data types, the following sections will discuss
compliance, porting issues, and usage. <acronym>SQL</acronym> standards compliance, porting issues, and usage.
Some <ProductName>Postgres</ProductName> types correspond directly to SQL92-compatible types. In other Some <ProductName>Postgres</ProductName> types correspond directly to
cases, data types defined by SQL92 syntax are mapped directly <acronym>SQL92</acronym>-compatible types. In other
cases, data types defined by <acronym>SQL92</acronym> syntax are mapped directly
into native <ProductName>Postgres</ProductName> types. into native <ProductName>Postgres</ProductName> types.
Many of the built-in types have obvious external formats. However, several Many of the built-in types have obvious external formats. However, several
types are either unique to <ProductName>Postgres</ProductName>, such as open and closed paths, or have types are either unique to <ProductName>Postgres</ProductName>,
such as open and closed paths, or have
several possibilities for formats, such as date and time types. several possibilities for formats, such as date and time types.
</Para> </Para>
@ -94,6 +98,11 @@ several possibilities for formats, such as date and time types.
<ENTRY>numeric(p,s)</ENTRY> <ENTRY>numeric(p,s)</ENTRY>
<ENTRY>exact numeric for p == 9, s = 0</ENTRY> <ENTRY>exact numeric for p == 9, s = 0</ENTRY>
</ROW> </ROW>
<ROW>
<ENTRY>int8</ENTRY>
<ENTRY></ENTRY>
<ENTRY>signed 8-byte integer</ENTRY>
</ROW>
<ROW> <ROW>
<ENTRY>line</ENTRY> <ENTRY>line</ENTRY>
<ENTRY></ENTRY> <ENTRY></ENTRY>
@ -124,6 +133,11 @@ several possibilities for formats, such as date and time types.
<ENTRY></ENTRY> <ENTRY></ENTRY>
<ENTRY>closed geometric path in 2D plane</ENTRY> <ENTRY>closed geometric path in 2D plane</ENTRY>
</ROW> </ROW>
<ROW>
<ENTRY>serial</ENTRY>
<ENTRY></ENTRY>
<ENTRY>unique id for indexing and cross-reference</ENTRY>
</ROW>
<ROW> <ROW>
<ENTRY>time</ENTRY> <ENTRY>time</ENTRY>
<ENTRY>time</ENTRY> <ENTRY>time</ENTRY>
@ -188,14 +202,16 @@ several possibilities for formats, such as date and time types.
</Para> </Para>
<Para> <Para>
<ProductName>Postgres</ProductName> has features at the forefront of ORDBMS development. In addition to <ProductName>Postgres</ProductName> has features at the forefront of
SQL3 conformance, substantial portions of SQL92 are also supported. <acronym>ORDBMS</acronym> development. In addition to
Although we strive for SQL92 compliance, there are some aspects of the standard <acronym>SQL3</acronym> conformance, substantial portions
of <acronym>SQL92</acronym> are also supported.
Although we strive for <acronym>SQL92</acronym> compliance,
there are some aspects of the standard
which are ill considered and which should not live through subsequent standards. which are ill considered and which should not live through subsequent standards.
<ProductName>Postgres</ProductName> will not make great efforts to conform to these aspects; <ProductName>Postgres</ProductName> will not make great efforts to
however, these conform to these features; however, these tend to apply in little-used
tend to apply in little-used or obsure cases, and a typical user is not likely to or obsure cases, and a typical user is not likely to run into them.
run into them.
<Para> <Para>
Most of the input and output functions corresponding to the Most of the input and output functions corresponding to the
@ -218,8 +234,9 @@ the original input.
The original <ProductName>Postgres</ProductName> v4.2 code received from The original <ProductName>Postgres</ProductName> v4.2 code received from
Berkeley rounded all double precision floating point results to six digits for Berkeley rounded all double precision floating point results to six digits for
output. Starting with v6.1, floating point numbers are allowed to retain output. Starting with v6.1, floating point numbers are allowed to retain
most of the intrinsic precision of the type (typically 15 digits for doubles, 6 digits most of the intrinsic precision of the type (typically 15 digits for doubles,
for 4-byte floats). Other types with underlying floating point fields (e.g. geometric 6 digits for 4-byte floats).
Other types with underlying floating point fields (e.g. geometric
types) carry similar precision. types) carry similar precision.
</note> </note>
</Para> </Para>
@ -245,6 +262,18 @@ floating point numbers.
</ROW> </ROW>
</THEAD> </THEAD>
<TBODY> <TBODY>
<ROW>
<ENTRY>float4</ENTRY>
<ENTRY>4 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY>
<ENTRY>6 decimal places</ENTRY>
</ROW>
<ROW>
<ENTRY>float8</ENTRY>
<ENTRY>8 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY>
<ENTRY>15 decimal places</ENTRY>
</ROW>
<ROW> <ROW>
<ENTRY>int2</ENTRY> <ENTRY>int2</ENTRY>
<ENTRY>2 bytes</ENTRY> <ENTRY>2 bytes</ENTRY>
@ -264,27 +293,64 @@ floating point numbers.
<ENTRY>+/- &gt; 18 decimal places</ENTRY> <ENTRY>+/- &gt; 18 decimal places</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>float4</ENTRY> <ENTRY>serial</ENTRY>
<ENTRY>4 bytes</ENTRY> <ENTRY>4 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY> <ENTRY>Identifer or cross-reference</ENTRY>
<ENTRY>6 decimal places</ENTRY> <ENTRY>0 to +2147483647</ENTRY>
</ROW>
<ROW>
<ENTRY>float8</ENTRY>
<ENTRY>8 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY>
<ENTRY>15 decimal places</ENTRY>
</ROW> </ROW>
</TBODY> </TBODY>
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
<para>
The numeric types have a full set of corresponding arithmetic operators and
functions. Refer to <xref linkend="math-opers" endterm="math-opers">
and <xref linkend="math-funcs" endterm="math-funcs"> for more information.
<para>
The <type>serial</type> type is a special-case type constructed by
<productname>Postgres</productname> from other existing components.
It is typically used to create unique identifiers for table entries.
In the current implementation, specifying
<programlisting>
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
</programlisting>
is equivalent to specifying:
<programlisting>
CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq;
CREATE TABLE <replaceable class="parameter">tablename</replaceable>
(<replaceable class="parameter">colname</replaceable> INT4 DEFAULT nextval('<replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq');
CREATE UNIQUE INDEX <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_key on <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable>);
</programlisting>
<caution>
<para>
The implicit sequence created for the <type>serial</type> type will
<emphasis>not</emphasis> be automatically removed when the table is dropped.
So, the following commands executed in order will likely fail:
<programlisting>
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
DROP TABLE <replaceable class="parameter">tablename</replaceable>;
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
</programlisting>
The sequence will remain in the database until explicitly dropped using
<command>DROP SEQUENCE</command>.
</caution>
<Para> <Para>
The <FirstTerm>exact numerics</FirstTerm> <Type>decimal</Type> and <Type>numeric</Type> The <FirstTerm>exact numerics</FirstTerm> <Type>decimal</Type> and
have fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3) <Type>numeric</Type>
have fully implemented syntax but currently
(<ProductName>Postgres</ProductName> v6.4)
support only a small range of precision and/or range values. support only a small range of precision and/or range values.
The <type>int8</type> type may not be available on all platforms. The <type>int8</type> type may not be available on all platforms since
it relies on compiler support for this.
</Para> </Para>
</Sect1> </Sect1>
@ -293,9 +359,12 @@ The <type>int8</type> type may not be available on all platforms.
<Title>Monetary Type</Title> <Title>Monetary Type</Title>
<Para> <Para>
The <Type>money</Type> type supports US-style currency with fixed decimal point representation. The <Type>money</Type> type supports US-style currency with
If <ProductName>Postgres</ProductName> is compiled with USE_LOCALE then the money type fixed decimal point representation.
should use the monetary conventions defined for locale(7). If <ProductName>Postgres</ProductName> is compiled with USE_LOCALE
then the money type
should use the monetary conventions defined for
<citetitle>locale(7)</citetitle>.
<Para> <Para>
<TABLE TOCENTRY="1"> <TABLE TOCENTRY="1">
@ -323,11 +392,12 @@ should use the monetary conventions defined for locale(7).
</Para> </Para>
<Para> <Para>
The <FirstTerm>numeric</FirstTerm> <type>numeric</type>
should eventually replace the money type. It has a should eventually replace the money type. It has a
fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3) fully implemented syntax but currently
support only a small range of precision and/or range values and cannot substitute for (<ProductName>Postgres</ProductName> v6.4)
the money type. support only a small range of precision and/or range values
and cannot adequately substitute for the money type.
</Para> </Para>
</Sect1> </Sect1>
@ -336,9 +406,11 @@ the money type.
<Title>Character Types</Title> <Title>Character Types</Title>
<Para> <Para>
<Acronym>SQL92</Acronym> defines two primary character types: <Type>char</Type> and <Acronym>SQL92</Acronym> defines two primary character types:
<Type>varchar</Type>. <ProductName>Postgres</ProductName> supports these types, in <Type>char</Type> and <Type>varchar</Type>.
addition to the more general <Type>text</Type> type, which unlike <Type>varchar</Type> <ProductName>Postgres</ProductName> supports these types, in
addition to the more general <Type>text</Type> type,
which unlike <Type>varchar</Type>
does not require an upper does not require an upper
limit to be declared on the size of the field. limit to be declared on the size of the field.
</Para> </Para>
@ -360,13 +432,13 @@ limit to be declared on the size of the field.
<ROW> <ROW>
<ENTRY>char</ENTRY> <ENTRY>char</ENTRY>
<ENTRY>1 byte</ENTRY> <ENTRY>1 byte</ENTRY>
<ENTRY>SQL92-compatible</ENTRY> <ENTRY><acronym>SQL92</acronym>-compatible</ENTRY>
<ENTRY>Single character</ENTRY> <ENTRY>Single character</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>char(n)</ENTRY> <ENTRY>char(n)</ENTRY>
<ENTRY>(4+n) bytes</ENTRY> <ENTRY>(4+n) bytes</ENTRY>
<ENTRY>SQL92-compatible</ENTRY> <ENTRY><acronym>SQL92</acronym>-compatible</ENTRY>
<ENTRY>Fixed-length blank padded</ENTRY> <ENTRY>Fixed-length blank padded</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -378,7 +450,7 @@ limit to be declared on the size of the field.
<ROW> <ROW>
<ENTRY>varchar(n)</ENTRY> <ENTRY>varchar(n)</ENTRY>
<ENTRY>(4+n) bytes</ENTRY> <ENTRY>(4+n) bytes</ENTRY>
<ENTRY>SQL92-compatible</ENTRY> <ENTRY><acronym>SQL92</acronym>-compatible</ENTRY>
<ENTRY>Variable-length with limit</ENTRY> <ENTRY>Variable-length with limit</ENTRY>
</ROW> </ROW>
</TBODY> </TBODY>
@ -387,10 +459,14 @@ limit to be declared on the size of the field.
</Para> </Para>
<Para> <Para>
There is currently one other fixed-length character type. The <Type>name</Type> type There is one other fixed-length character type.
only has one purpose and that is to provide <ProductName>Postgres</ProductName> with a The <Type>name</Type> type
special type to use for internal names. It is not intended for use by the general user. only has one purpose and that is to provide
It's length is currently defined as 32 chars but should be reference using NAMEDATALEN. <ProductName>Postgres</ProductName> with a
special type to use for internal names.
It is not intended for use by the general user.
It's length is currently defined as 32 chars
but should be reference using NAMEDATALEN.
This is set at compile time and may change in a future release. This is set at compile time and may change in a future release.
</Para> </Para>
@ -423,10 +499,13 @@ This is set at compile time and may change in a future release.
<Title>Date/Time Types</Title> <Title>Date/Time Types</Title>
<Para> <Para>
There are two fundamental kinds of date and time measurements: clock time and time interval. There are two fundamental kinds of date and time measurements:
clock time and time interval.
Both quantities have continuity and smoothness, as does time itself. Both quantities have continuity and smoothness, as does time itself.
<ProductName>Postgres</ProductName> supplies two primary user-oriented date and time types, <ProductName>Postgres</ProductName> supplies two primary user-oriented
<Type>datetime</Type> and timespan, as well as the related SQL92 types date and time. date and time types,
<Type>datetime</Type> and timespan, as well as
the related <acronym>SQL92</acronym> types date and time.
</Para> </Para>
<Para> <Para>
@ -458,7 +537,7 @@ for historical reasons.
<ROW> <ROW>
<ENTRY>date</ENTRY> <ENTRY>date</ENTRY>
<ENTRY>4 bytes</ENTRY> <ENTRY>4 bytes</ENTRY>
<ENTRY>SQL92 type</ENTRY> <ENTRY><acronym>SQL92</acronym> type</ENTRY>
<ENTRY>wide range</ENTRY> <ENTRY>wide range</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -470,7 +549,7 @@ for historical reasons.
<ROW> <ROW>
<ENTRY>interval</ENTRY> <ENTRY>interval</ENTRY>
<ENTRY>12 bytes</ENTRY> <ENTRY>12 bytes</ENTRY>
<ENTRY>SQL92 type</ENTRY> <ENTRY><acronym>SQL92</acronym> type</ENTRY>
<ENTRY>equivalent to timespan</ENTRY> <ENTRY>equivalent to timespan</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -482,7 +561,7 @@ for historical reasons.
<ROW> <ROW>
<ENTRY>time</ENTRY> <ENTRY>time</ENTRY>
<ENTRY>4 bytes</ENTRY> <ENTRY>4 bytes</ENTRY>
<ENTRY>SQL92 type</ENTRY> <ENTRY><acronym>SQL92</acronym> type</ENTRY>
<ENTRY>wide range</ENTRY> <ENTRY>wide range</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -494,7 +573,7 @@ for historical reasons.
<ROW> <ROW>
<ENTRY>timestamp</ENTRY> <ENTRY>timestamp</ENTRY>
<ENTRY>4 bytes</ENTRY> <ENTRY>4 bytes</ENTRY>
<ENTRY>SQL92 type</ENTRY> <ENTRY><acronym>SQL92</acronym> type</ENTRY>
<ENTRY>limited range</ENTRY> <ENTRY>limited range</ENTRY>
</ROW> </ROW>
</TBODY> </TBODY>
@ -525,19 +604,19 @@ for historical reasons.
<ROW> <ROW>
<ENTRY>date</ENTRY> <ENTRY>date</ENTRY>
<ENTRY>4713 BC</ENTRY> <ENTRY>4713 BC</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>32767 AD</ENTRY>
<ENTRY>1 day</ENTRY> <ENTRY>1 day</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>datetime</ENTRY> <ENTRY>datetime</ENTRY>
<ENTRY>4713 BC</ENTRY> <ENTRY>4713 BC</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>1465001 AD</ENTRY>
<ENTRY>1 microsec to 14 digits</ENTRY> <ENTRY>1 microsec to 14 digits</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>interval</ENTRY> <ENTRY>interval</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>-178000000 years</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>178000000 years</ENTRY>
<ENTRY>1 microsec</ENTRY> <ENTRY>1 microsec</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -554,8 +633,8 @@ for historical reasons.
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>timespan</ENTRY> <ENTRY>timespan</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>-178000000 years</ENTRY>
<ENTRY>no limit</ENTRY> <ENTRY>178000000 years</ENTRY>
<ENTRY>1 microsec (14 digits)</ENTRY> <ENTRY>1 microsec (14 digits)</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
@ -573,26 +652,33 @@ for historical reasons.
<ProductName>Postgres</ProductName> endevours to be compatible with <ProductName>Postgres</ProductName> endevours to be compatible with
<Acronym>SQL92</Acronym> definitions for typical usage. <Acronym>SQL92</Acronym> definitions for typical usage.
The <Acronym>SQL92</Acronym> standard has an odd mix of date and The <Acronym>SQL92</Acronym> standard has an odd mix of date and
time types and capabilities. For example, although the date type does not have an associated time zone, the time types and capabilities. For example, although the date type
time type can. The default time zone is specified as a constant offset from GMT/UTC; does not have an associated time zone, the
however, time zones in the real world can have no meaning unless associated with a time type can. The default time zone is specified as a constant offset
date as well from GMT/UTC;
however, time zones in the real world can have no meaning unless
associated with a date as well
as a time since the offset will vary through the year. as a time since the offset will vary through the year.
<Para> <Para>
To obviate these difficulties, <ProductName>Postgres</ProductName> associates time zones To address these difficulties, <ProductName>Postgres</ProductName>
only with date and time associates time zones only with date and time
types which contain both date and time, and assumes local time for any type containing only types which contain both date and time,
date or time. Further, time zone support is derived from the underlying operating system and assumes local time for any type containing only
time zone capabilities, and hence can handle daylight savings time and other expected behavior. date or time. Further, time zone support is derived from
the underlying operating system
time zone capabilities, and hence can handle daylight savings time
and other expected behavior.
<Para> <Para>
In future releases, the number of date/time types will decrease, with the current In future releases, the number of date/time types will decrease,
implementation of <Type>datetime</Type> becoming <Type>timestamp</Type>, timespan becoming interval, with the current implementation of
and (possibly) abstime <Type>datetime</Type> becoming <Type>timestamp</Type>,
and reltime being deprecated in favor of <Type>timestamp</Type> and interval. <Type>timespan</Type> becoming <Type>interval</Type>,
The more arcane features and (possibly) <Type>abstime</Type> and <Type>reltime</Type>
of the date/time definitions from the <Acronym>SQL92</Acronym> standard are not likely to be pursued. being deprecated in favor of <Type>timestamp</Type> and <Type>interval</Type>.
The more arcane features of the date/time definitions from
the <Acronym>SQL92</Acronym> standard are not likely to be pursued.
</Para> </Para>
<Sect2> <Sect2>
@ -600,7 +686,7 @@ of the date/time definitions from the <Acronym>SQL92</Acronym> standard are not
<Para> <Para>
Output formats can be set to one of four styles: Output formats can be set to one of four styles:
ISO-8601, SQL (Ingres), traditional ISO-8601, <acronym>SQL</acronym> (Ingres), traditional
Postgres, and German. Postgres, and German.
<TABLE TOCENTRY="1"> <TABLE TOCENTRY="1">
@ -621,7 +707,7 @@ Postgres, and German.
<ENTRY>1997-12-17 07:37:16-08</ENTRY> <ENTRY>1997-12-17 07:37:16-08</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>SQL</ENTRY> <ENTRY><acronym>SQL</acronym></ENTRY>
<ENTRY>Traditional style</ENTRY> <ENTRY>Traditional style</ENTRY>
<ENTRY>12/17/1997 07:37:16.00 PST</ENTRY> <ENTRY>12/17/1997 07:37:16.00 PST</ENTRY>
</ROW> </ROW>
@ -641,8 +727,8 @@ Postgres, and German.
</Para> </Para>
<Para> <Para>
The SQL style has European and non-European (US) variants, which determines whether The <acronym>SQL</acronym> style has European and non-European (US) variants,
month follows day or vica versa. which determines whether month follows day or vica versa.
<TABLE TOCENTRY="1"> <TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Date Order Conventions</TITLE> <TITLE><ProductName>Postgres</ProductName> Date Order Conventions</TITLE>
@ -682,12 +768,14 @@ There are several ways to affect the appearance of date/time types:
<ItemizedList Mark="bullet" Spacing="compact"> <ItemizedList Mark="bullet" Spacing="compact">
<ListItem> <ListItem>
<Para> <Para>
The PGDATESTYLE environment variable used by the backend directly on postmaster startup. The PGDATESTYLE environment variable used by the backend directly
on postmaster startup.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
The PGDATESTYLE environment variable used by the frontend libpq on session startup. The PGDATESTYLE environment variable used by the frontend libpq
on session startup.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
@ -698,8 +786,10 @@ SET DateStyle <Acronym>SQL</Acronym> command.
</ItemizedList> </ItemizedList>
<Para> <Para>
For <ProductName>Postgres</ProductName> v6.3 (and earlier) the default date/time style is For <ProductName>Postgres</ProductName> v6.4 (and earlier)
"non-European traditional Postgres". In future releases, the default may become ISO-8601, which alleviates the default date/time style is
"non-European traditional Postgres".
In future releases, the default may become ISO-8601, which alleviates
date specification ambiguities and Y2K collation problems. date specification ambiguities and Y2K collation problems.
</Para> </Para>
@ -709,9 +799,11 @@ date specification ambiguities and Y2K collation problems.
<Title>Time Zones</Title> <Title>Time Zones</Title>
<Para> <Para>
<ProductName>Postgres</ProductName> obtains time zone support from the underlying operating system. <ProductName>Postgres</ProductName> obtains time zone support
All dates and times are stored internally in Universal Coordinated Time (UTC), alternately known as from the underlying operating system.
Greenwich Mean Time (GMT). Times are converted to local time on the database server before being All dates and times are stored internally in Universal Coordinated Time (UTC),
alternately known as Greenwich Mean Time (GMT).
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. sent to the client frontend, hence by default are in the server time zone.
<Para> <Para>
@ -726,12 +818,14 @@ The TZ environment variable used by the backend directly
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
The PGTZ environment variable set at the client used by libpq to send time zone information to the backend upon connection. The PGTZ environment variable set at the client used by libpq
to send time zone information to the backend upon connection.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Command>set timezone</Command> <Acronym>SQL</Acronym> sets the time zone for the session. The <Acronym>SQL</Acronym> command <Command>SET TIME ZONE</Command>
sets the time zone for the session.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
@ -747,21 +841,25 @@ the time zone becomes GMT (on most systems anyway).
<Para> <Para>
General-use date and time is input using a wide range of General-use date and time is input using a wide range of
styles, including ISO-compatible, SQL-compatible, traditional styles, including ISO-compatible, <acronym>SQL</acronym>-compatible,
<ProductName>Postgres</ProductName> traditional <ProductName>Postgres</ProductName>
and other permutations of date and time. In cases where interpretation and other permutations of date and time. In cases where interpretation
can be ambiguous (quite possible with many traditional styles of date specification) can be ambiguous (quite possible with many traditional styles of date
<ProductName>Postgres</ProductName> uses a style setting to resolve the ambiguity. specification) <ProductName>Postgres</ProductName> uses a style setting
to resolve the ambiguity.
</Para> </Para>
<Para> <Para>
Most date and time types share code for data input. For those types Most date and time types share code for data input. For those types
the input can have any of a wide variety of styles. For numeric date representations, the input can have any of a wide variety of styles. For numeric date
European and US conventions can differ, and the proper interpretation is obtained representations,
European and US conventions can differ, and the proper interpretation
is obtained
by using the by using the
<Command>set datestyle</Command> <Command>set datestyle</Command>
command before entering data. command before entering data.
Note that the style setting does not preclude use of various styles for input; it is Note that the style setting does not preclude use of various styles for input;
it is
used primarily to determine the output style and to resolve ambiguities. used primarily to determine the output style and to resolve ambiguities.
</Para> </Para>
@ -844,10 +942,11 @@ for it. `epoch' means Jan 1 00:00:00 1970 GMT.
<Para> <Para>
General-use date and time is input using a wide range of General-use date and time is input using a wide range of
styles, including ISO-compatible, SQL-compatible, traditional styles, including ISO-compatible, <acronym>SQL</acronym>-compatible, traditional
<ProductName>Postgres</ProductName> (see section on "absolute time") <ProductName>Postgres</ProductName> (see section on "absolute time")
and other permutations of date and time. Output styles can be ISO-compatible, and other permutations of date and time. Output styles can be ISO-compatible,
SQL-compatible, or traditional <ProductName>Postgres</ProductName>, with the default set to be compatible <acronym>SQL</acronym>-compatible, or traditional
<ProductName>Postgres</ProductName>, with the default set to be compatible
with <ProductName>Postgres</ProductName> v6.0. with <ProductName>Postgres</ProductName> v6.0.
</Para> </Para>
@ -881,13 +980,18 @@ translate time to the local time zone of the server.
<Para> <Para>
General-use time span is input using a wide range of General-use time span is input using a wide range of
syntaxes, including ISO-compatible, SQL-compatible, traditional syntaxes, including ISO-compatible, <acronym>SQL</acronym>-compatible,
traditional
<ProductName>Postgres</ProductName> (see section on "relative time") <ProductName>Postgres</ProductName> (see section on "relative time")
and other permutations of time span. Output formats can be ISO-compatible, and other permutations of time span. Output formats can be ISO-compatible,
SQL-compatible, or traditional <ProductName>Postgres</ProductName>, with the default set to be <ProductName>Postgres</ProductName>-compatible. <acronym>SQL</acronym>-compatible, or traditional
<ProductName>Postgres</ProductName>,
with the default set to be <ProductName>Postgres</ProductName>-compatible.
Months and years are a "qualitative" time interval, and are stored separately Months and years are a "qualitative" time interval, and are stored separately
from the other "quantitative" time intervals such as day or hour. For date arithmetic, from the other "quantitative" time intervals such as day or hour.
the qualitative time units are instantiated in the context of the relevant date or time. For date arithmetic,
the qualitative time units are instantiated in the context of the
relevant date or time.
<Para> <Para>
Time span is specified with the following syntax: Time span is specified with the following syntax:
@ -908,7 +1012,8 @@ where
<Title>abstime</Title> <Title>abstime</Title>
<Para> <Para>
Absolute time (abstime) is a limited-range (+/- 68 years) and limited-precision (1 sec) Absolute time (<type>abstime</type>) is a limited-range (+/- 68 years) and
limited-precision (1 sec)
date data type. <Type>datetime</Type> may be preferred, since it date data type. <Type>datetime</Type> may be preferred, since it
covers a larger range with greater precision. covers a larger range with greater precision.
@ -929,11 +1034,18 @@ where
<Para> <Para>
Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04 Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
2038 GMT. As of Version 3.0, times are no longer read and written 2038 GMT.
<note>
<title>Historical Note</title>
<para>
As of Version 3.0, times are no longer read and written
using Greenwich Mean Time; the input and output routines default to using Greenwich Mean Time; the input and output routines default to
the local time zone. the local time zone.
</note>
All special values allowed for <Type>datetime</Type> are also allowed for "absolute time". All special values allowed for <Type>datetime</Type> are also
allowed for "absolute time".
</Para> </Para>
</Sect2> </Sect2>
@ -945,15 +1057,20 @@ All special values allowed for <Type>datetime</Type> are also allowed for "absol
Relative time <Type>reltime</Type> is a limited-range (+/- 68 years) Relative time <Type>reltime</Type> is a limited-range (+/- 68 years)
and limited-precision (1 sec) time span data type. and limited-precision (1 sec) time span data type.
<Type>timespan</Type> should be preferred, since it <Type>timespan</Type> should be preferred, since it
covers a larger range with greater precision and, more importantly, can distinguish between covers a larger range with greater precision and, more importantly,
relative units (months and years) and quantitative units (days, hours, etc). Instead, reltime can distinguish between
must force months to be exactly 30 days, so time arithmetic does not always work as expected. relative units (months and years) and quantitative units (days, hours, etc).
For example, adding one reltime year to abstime today does not produce today's date one year from Instead, reltime
must force months to be exactly 30 days, so time arithmetic does not
always work as expected.
For example, adding one reltime year to abstime today does not
produce today's date one year from
now, but rather a date 360 days from today. now, but rather a date 360 days from today.
</Para> </Para>
<Para> <Para>
<Type>reltime</Type> shares input and output routines with the other time span types. <Type>reltime</Type> shares input and output routines with the other
time span types.
The section on <Type>timespan</Type> covers this in more detail. The section on <Type>timespan</Type> covers this in more detail.
</Para> </Para>
@ -966,12 +1083,14 @@ The section on <Type>timespan</Type> covers this in more detail.
This is currently a limited-range absolute time which closely resembles the This is currently a limited-range absolute time which closely resembles the
abstime abstime
data type. It shares the general input parser with the other date/time types. data type. It shares the general input parser with the other date/time types.
In future releases this type will absorb the capabilities of the <Type>datetime</Type> type In future releases this type will absorb the capabilities of the
and will move toward SQL92 compliance. <Type>datetime</Type> type
and will move toward <acronym>SQL92</acronym> compliance.
</Para> </Para>
<Para> <Para>
<Type>timestamp</Type> is specified using the same syntax as for <Type>datetime</Type>. <Type>timestamp</Type> is specified using the same syntax as for
<Type>datetime</Type>.
</Para> </Para>
</Sect2> </Sect2>
@ -980,8 +1099,8 @@ and will move toward SQL92 compliance.
<Para> <Para>
<Type>interval</Type> is an <Acronym>SQL92</Acronym> data type which is <Type>interval</Type> is an <Acronym>SQL92</Acronym> data type which is
currently mapped to the <Type>timespan</Type> <ProductName>Postgres</ProductName> currently mapped to the <Type>timespan</Type>
data type. <ProductName>Postgres</ProductName> data type.
</Para> </Para>
</Sect2> </Sect2>
@ -1009,9 +1128,12 @@ Special abstime values such as
<Para> <Para>
<ProductName>Postgres</ProductName> supports <Type>bool</Type> as <ProductName>Postgres</ProductName> supports <Type>bool</Type> as
the <Acronym>SQL3</Acronym> boolean type. the <Acronym>SQL3</Acronym> boolean type.
<Type>bool</Type> can have one of only two states: 'true' or 'false'. A third state, 'unknown', is not <Type>bool</Type> can have one of only two states: 'true' or 'false'.
implemented and is not suggested in <Acronym>SQL3</Acronym>; <Acronym>NULL</Acronym> is an A third state, 'unknown', is not
effective substitute. <Type>bool</Type> can be used in any boolean expression, and boolean expressions implemented and is not suggested in <Acronym>SQL3</Acronym>;
<Acronym>NULL</Acronym> is an
effective substitute. <Type>bool</Type> can be used in any boolean expression,
and boolean expressions
always evaluate to a result compatible with this type. always evaluate to a result compatible with this type.
<Para> <Para>
@ -1051,7 +1173,8 @@ always evaluate to a result compatible with this type.
<Title>Geometric Types</Title> <Title>Geometric Types</Title>
<Para> <Para>
Geometric types represent two-dimensional spatial objects. The most fundamental type, Geometric types represent two-dimensional spatial objects.
The most fundamental type,
the point, forms the basis for all of the other types. the point, forms the basis for all of the other types.
</Para> </Para>
@ -1124,7 +1247,8 @@ the point, forms the basis for all of the other types.
<Para> <Para>
A rich set of functions and operators is available to perform various geometric A rich set of functions and operators is available to perform various geometric
operations such as scaling, translation, rotation, and determining intersections. operations such as scaling, translation, rotation, and determining
intersections.
</Para> </Para>
<Sect2> <Sect2>
@ -1222,9 +1346,11 @@ where
</ProgramListing> </ProgramListing>
Paths are output using the first syntax. Paths are output using the first syntax.
Note that <ProductName>Postgres</ProductName> versions prior to Note that <ProductName>Postgres</ProductName> versions prior to
v6.1 used a format for paths which had a single leading parenthesis, a "closed" flag, v6.1 used a format for paths which had a single leading parenthesis,
a "closed" flag,
an integer count of the number of points, then the list of points followed by a an integer count of the number of points, then the list of points followed by a
closing parenthesis. The built-in function <Function>upgradepath</Function> is supplied to convert closing parenthesis.
The built-in function <Function>upgradepath</Function> is supplied to convert
paths dumped and reloaded from pre-v6.1 databases. paths dumped and reloaded from pre-v6.1 databases.
</Para> </Para>
</Sect2> </Sect2>
@ -1234,9 +1360,8 @@ paths dumped and reloaded from pre-v6.1 databases.
<Para> <Para>
Polygons are represented by sets of points. Polygons should probably be Polygons are represented by sets of points. Polygons should probably be
considered considered equivalent to closed paths, but are stored differently
equivalent to closed paths, but are stored differently and have their own and have their own set of support routines.
set of support routines.
</Para> </Para>
<Para> <Para>
@ -1254,7 +1379,8 @@ where
Polygons are output using the first syntax. Polygons are output using the first syntax.
Note that <ProductName>Postgres</ProductName> versions prior to Note that <ProductName>Postgres</ProductName> versions prior to
v6.1 used a format for polygons which had a single leading parenthesis, the list v6.1 used a format for polygons which had a single leading parenthesis, the list
of x-axis coordinates, the list of y-axis coordinates, followed by a closing parenthesis. of x-axis coordinates, the list of y-axis coordinates,
followed by a closing parenthesis.
The built-in function <Function>upgradepoly</Function> is supplied to convert The built-in function <Function>upgradepoly</Function> is supplied to convert
polygons dumped and reloaded from pre-v6.1 databases. polygons dumped and reloaded from pre-v6.1 databases.
</Para> </Para>