Skip to content

P
Postgres FD Implementation
Commit 4f1766f1 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Try to clarify characteristics of the SERIAL type. 

Fix source indenting, which does not affect output.
Note: still need docs on NUMERIC and DECIMAL
 (and let's not talk about regression tests :()
parent e1fad50a
Show whitespace changes
Inline Side-by-side
Showing with 806 additions and 777 deletions
doc/src/sgml/datatype.sgml
View file @ 4f1766f1
...@@ -265,22 +265,23 @@ ...@@ -265,22 +265,23 @@
<para> <para>
Numeric types consist of two- and four-byte integers and four- and eight-byte Numeric types consist of two- and four-byte integers and four- and eight-byte
floating point numbers.</para> floating point numbers.
</para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Numeric Types</title> <title><productname>Postgres</productname> Numeric Types</title>
<titleabbrev>Numerics</titleabbrev> <titleabbrev>Numerics</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>Numeric Type</entry> <entry>Numeric Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Range</entry> <entry>Range</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>float4</entry> <entry>float4</entry>
<entry>4 bytes</entry> <entry>4 bytes</entry>
...@@ -317,130 +318,147 @@ ...@@ -317,130 +318,147 @@
<entry>Identifer or cross-reference</entry> <entry>Identifer or cross-reference</entry>
<entry>0 to +2147483647</entry> <entry>0 to +2147483647</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <para>
The numeric types have a full set of corresponding arithmetic operators and The numeric types have a full set of corresponding arithmetic operators and
functions. Refer to <xref endterm="math-opers" linkend="math-opers"> functions. Refer to <xref endterm="math-opers" linkend="math-opers">
and <xref endterm="math-funcs" linkend="math-funcs"> for more information. and <xref endterm="math-funcs" linkend="math-funcs"> for more information.
</para> </para>
<para> <para>
The <type>serial</type> type is a special-case type constructed by The <type>int8</type> type may not be available on all platforms since
<productname>Postgres</productname> from other existing components. it relies on compiler support for this.
It is typically used to create unique identifiers for table entries. </para>
In the current implementation, specifying
<sect2>
<title>The Serial Type</title>
<programlisting> <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); CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
</programlisting> </programlisting>
is equivalent to specifying: is equivalent to specifying:
<programlisting> <programlisting>
CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq; CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq;
CREATE TABLE <replaceable class="parameter">tablename</replaceable> 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'); (<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>); 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> </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.
</para>
</caution>
<caution> Implicit sequences supporting the <type>serial</type> are
<para> not automatically dropped when a table containing a serial type
The implicit sequence created for the <type>serial</type> type will is dropped. So, the following commands executed in order will likely fail:
<emphasis>not</emphasis> be automatically removed when the table is dropped.
So, the following commands executed in order will likely fail:
<programlisting> <programlisting>
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL); CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
DROP TABLE <replaceable class="parameter">tablename</replaceable>; DROP TABLE <replaceable class="parameter">tablename</replaceable>;
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL); CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
</programlisting> </programlisting>
The sequence will remain in the database until explicitly dropped using The sequence will remain in the database until explicitly dropped using
<command>DROP SEQUENCE</command>.</para> <command>DROP SEQUENCE</command>.
</caution>
</para> </para>
</sect2>
<para> </sect1>
The <type>int8</type> type may not be available on all platforms since
it relies on compiler support for this.
</para>
</sect1> <sect1>
<title>Monetary Type</title>
<sect1> <note>
<title>Monetary Type</title> <title>Obsolete Type</title>
<para>
The <type>money</type> is now obsolete. Use <type>numeric</type>
or <type>decimal</type> instead.
</para>
</note>
<para> <para>
The <type>money</type> type supports US-style currency with The <type>money</type> type supports US-style currency with
fixed decimal point representation. fixed decimal point representation.
If <productname>Postgres</productname> is compiled with USE_LOCALE If <productname>Postgres</productname> is compiled with USE_LOCALE
then the money type should use the monetary conventions defined for then the money type should use the monetary conventions defined for
<citetitle>locale(7)</citetitle>. <citetitle>locale(7)</citetitle>.
</para> </para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Monetary Types</title> <title><productname>Postgres</productname> Monetary Types</title>
<titleabbrev>Money</titleabbrev> <titleabbrev>Money</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>Monetary Type</entry> <entry>Monetary Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Range</entry> <entry>Range</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>money</entry> <entry>money</entry>
<entry>4 bytes</entry> <entry>4 bytes</entry>
<entry>Fixed-precision</entry> <entry>Fixed-precision</entry>
<entry>-21474836.48 to +21474836.47</entry> <entry>-21474836.48 to +21474836.47</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <para>
<type>numeric</type> <type>numeric</type>
will replace the money type, and should be preferred. will replace the money type, and should be preferred.
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Character Types</title> <title>Character Types</title>
<para> <para>
<acronym>SQL92</acronym> defines two primary character types: <acronym>SQL92</acronym> defines two primary character types:
<type>char</type> and <type>varchar</type>. <type>char</type> and <type>varchar</type>.
<productname>Postgres</productname> supports these types, in <productname>Postgres</productname> supports these types, in
addition to the more general <type>text</type> type, addition to the more general <type>text</type> type,
which unlike <type>varchar</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>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Character Types</title> <title><productname>Postgres</productname> Character Types</title>
<titleabbrev>Characters</titleabbrev> <titleabbrev>Characters</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>Character Type</entry> <entry>Character Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Recommendation</entry> <entry>Recommendation</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>char</entry> <entry>char</entry>
<entry>1 byte</entry> <entry>1 byte</entry>
...@@ -465,47 +483,47 @@ limit to be declared on the size of the field. ...@@ -465,47 +483,47 @@ limit to be declared on the size of the field.
<entry><acronym>SQL92</acronym>-compatible</entry> <entry><acronym>SQL92</acronym>-compatible</entry>
<entry>Variable-length with limit</entry> <entry>Variable-length with limit</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <para>
There is one other fixed-length character type. There is one other fixed-length character type.
The <type>name</type> type The <type>name</type> type
only has one purpose and that is to provide only has one purpose and that is to provide
<productname>Postgres</productname> with a <productname>Postgres</productname> with a
special type to use for internal names. special type to use for internal names.
It is not intended for use by the general user. It is not intended for use by the general user.
It's length is currently defined as 32 chars It's length is currently defined as 32 chars
but should be reference using NAMEDATALEN. 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>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Specialty Character Type</title> <title><productname>Postgres</productname> Specialty Character Type</title>
<titleabbrev>Specialty Characters</titleabbrev> <titleabbrev>Specialty Characters</titleabbrev>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
<entry>Character Type</entry> <entry>Character Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>name</entry> <entry>name</entry>
<entry>32 bytes</entry> <entry>32 bytes</entry>
<entry>Thirty-two character internal type</entry> <entry>Thirty-two character internal type</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Date/Time Types</title> <title>Date/Time Types</title>
...@@ -728,26 +746,26 @@ This is set at compile time and may change in a future release. ...@@ -728,26 +746,26 @@ This is set at compile time and may change in a future release.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Date/Time Styles</title> <title>Date/Time Styles</title>
<para> <para>
Output formats can be set to one of four styles: Output formats can be set to one of four styles:
ISO-8601, <acronym>SQL</acronym> (Ingres), traditional ISO-8601, <acronym>SQL</acronym> (Ingres), traditional
Postgres, and German. Postgres, and German.
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Date Styles</title> <title><productname>Postgres</productname> Date Styles</title>
<titleabbrev>Styles</titleabbrev> <titleabbrev>Styles</titleabbrev>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
<entry>Style Specification</entry> <entry>Style Specification</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Example</entry> <entry>Example</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>ISO</entry> <entry>ISO</entry>
<entry>ISO-8601 standard</entry> <entry>ISO-8601 standard</entry>
...@@ -768,27 +786,27 @@ Postgres, and German. ...@@ -768,27 +786,27 @@ Postgres, and German.
<entry>Regional style</entry> <entry>Regional style</entry>
<entry>17.12.1997 07:37:16.00 PST</entry> <entry>17.12.1997 07:37:16.00 PST</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <para>
The <acronym>SQL</acronym> style has European and non-European (US) variants, The <acronym>SQL</acronym> style has European and non-European (US) variants,
which determines whether 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>
<titleabbrev>Order</titleabbrev> <titleabbrev>Order</titleabbrev>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
<entry>Style Specification</entry> <entry>Style Specification</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Example</entry> <entry>Example</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>European</entry> <entry>European</entry>
<entry>Regional convention</entry> <entry>Regional convention</entry>
...@@ -804,37 +822,37 @@ which determines whether month follows day or vica versa. ...@@ -804,37 +822,37 @@ which determines whether month follows day or vica versa.
<entry>Regional convention</entry> <entry>Regional convention</entry>
<entry>12/17/1997 07:37:16.00 PST</entry> <entry>12/17/1997 07:37:16.00 PST</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<para> <para>
There are several ways to affect the appearance of date/time types: There are several ways to affect the appearance of date/time types:
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
<listitem> <listitem>
<para> <para>
The PGDATESTYLE environment variable used by the backend directly The <envar>PGDATESTYLE</envar> environment variable used by the backend directly
on postmaster startup. on postmaster startup.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The PGDATESTYLE environment variable used by the frontend libpq The <envar>PGDATESTYLE</envar> environment variable used by the frontend libpq
on session startup. on session startup.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<command>SET DATESTYLE</command> <acronym>SQL</acronym> command. <command>SET DATESTYLE</command> <acronym>SQL</acronym> command.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
For <productname>Postgres</productname> v6.4 (and earlier) For <productname>Postgres</productname> v6.5 (and earlier)
the default date/time style is the default date/time style is
"non-European traditional Postgres". "non-European traditional Postgres".
In future releases, the default may become "ISO" (compatible with ISO-8601), In future releases, the default may become "ISO" (compatible with ISO-8601),
...@@ -901,7 +919,8 @@ on session startup. ...@@ -901,7 +919,8 @@ on session startup.
sets the time zone for the session. sets the time zone for the session.
</para> </para>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist>
</para>
<para> <para>
If an invalid time zone is specified, If an invalid time zone is specified,
...@@ -1291,22 +1310,22 @@ on session startup. ...@@ -1291,22 +1310,22 @@ on session startup.
</sect2> </sect2>
<sect2> <sect2>
<title>datetime</title> <title><type>datetime</type></title>
<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, <acronym>SQL</acronym>-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,
<acronym>SQL</acronym>-compatible, or traditional <acronym>SQL</acronym>-compatible, or traditional
<productname>Postgres</productname>, with the default set to be compatible <productname>Postgres</productname>, with the default set to be compatible
with <productname>Postgres</productname> v6.0. with <productname>Postgres</productname> v6.0.
</para> </para>
<para> <para>
<type>datetime</type> is specified using the following syntax: <type>datetime</type> is specified using the following syntax:
<programlisting> <programlisting>
Year-Month-Day [ Hour : Minute : Second ] [AD,BC] [ Timezone ] Year-Month-Day [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
YearMonthDay [ Hour : Minute : Second ] [AD,BC] [ Timezone ] YearMonthDay [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ] Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ]
...@@ -1318,40 +1337,41 @@ where ...@@ -1318,40 +1337,41 @@ where
Minute is 00, 01, ..., 59 Minute is 00, 01, ..., 59
Second is 00, 01, ..., 59 (60 for leap second) Second is 00, 01, ..., 59 (60 for leap second)
Timezone is 3 characters or ISO offset to GMT Timezone is 3 characters or ISO offset to GMT
</programlisting> </programlisting>
</para> </para>
<para> <para>
Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future. Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future.
Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible
offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time). offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time).
Dates are stored internally in Greenwich Mean Time. Input and output routines Dates are stored internally in Greenwich Mean Time. Input and output routines
translate time to the local time zone of the server. translate time to the local time zone of the server.
</para></sect2> </para>
</sect2>
<sect2> <sect2>
<title><type>timespan</type></title> <title><type>timespan</type></title>
<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, <acronym>SQL</acronym>-compatible, syntaxes, including ISO-compatible, <acronym>SQL</acronym>-compatible,
traditional 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,
<acronym>SQL</acronym>-compatible, or traditional <acronym>SQL</acronym>-compatible, or traditional
<productname>Postgres</productname>, <productname>Postgres</productname>,
with the default set to be <productname>Postgres</productname>-compatible. 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. from the other "quantitative" time intervals such as day or hour.
For date arithmetic, For date arithmetic,
the qualitative time units are instantiated in the context of the the qualitative time units are instantiated in the context of the
relevant date or time. relevant date or time.
</para> </para>
<para> <para>
Time span is specified with the following syntax: Time span is specified with the following syntax:
<programlisting> <programlisting>
Quantity Unit [Quantity Unit...] [Direction] Quantity Unit [Quantity Unit...] [Direction]
@ Quantity Unit [Direction] @ Quantity Unit [Direction]
where where
...@@ -1359,12 +1379,12 @@ where ...@@ -1359,12 +1379,12 @@ where
Unit is <literal>second</literal>, <literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>, <literal>week</literal>, <literal>month</literal>, <literal>year</literal>, Unit is <literal>second</literal>, <literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>, <literal>week</literal>, <literal>month</literal>, <literal>year</literal>,
<literal>decade</literal>, <literal>century</literal>, <literal>millenium</literal>, or abbreviations or plurals of these units. <literal>decade</literal>, <literal>century</literal>, <literal>millenium</literal>, or abbreviations or plurals of these units.
Direction is <literal>ago</literal>. Direction is <literal>ago</literal>.
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>abstime</title> <title><type>abstime</type></title>
<para> <para>
Absolute time (<type>abstime</type>) is a limited-range (+/- 68 years) and Absolute time (<type>abstime</type>) is a limited-range (+/- 68 years) and
...@@ -1373,10 +1393,10 @@ where ...@@ -1373,10 +1393,10 @@ where
covers a larger range with greater precision. covers a larger range with greater precision.
</para> </para>
<para> <para>
Absolute time is specified using the following syntax: Absolute time is specified using the following syntax:
<programlisting> <programlisting>
Month Day [ Hour : Minute : Second ] Year [ Timezone ] Month Day [ Hour : Minute : Second ] Year [ Timezone ]
where where
Month is Jan, Feb, ..., Dec Month is Jan, Feb, ..., Dec
...@@ -1385,130 +1405,133 @@ where ...@@ -1385,130 +1405,133 @@ where
Minute is 00, 01, ..., 59 Minute is 00, 01, ..., 59
Second is 00, 01, ..., 59 Second is 00, 01, ..., 59
Year is 1901, 1902, ..., 2038 Year is 1901, 1902, ..., 2038
</programlisting> </programlisting>
</para> </para>
<para> <para>
Valid dates are from <literal>Dec 13 20:45:53 1901 GMT</literal> Valid dates are from <literal>Dec 13 20:45:53 1901 GMT</literal>
to <literal>Jan 19 03:14:04 2038 GMT</literal>. to <literal>Jan 19 03:14:04 2038 GMT</literal>.
<note> <note>
<title>Historical Note</title> <title>Historical Note</title>
<para> <para>
As of Version 3.0, times are no longer read and written 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.</para> the local time zone.</para>
</note> </note>
All special values allowed for <type>datetime</type> are also All special values allowed for <type>datetime</type> are also
allowed for "absolute time". allowed for "absolute time".
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>reltime</title> <title><type>reltime</type></title>
<para> <para>
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, covers a larger range with greater precision and, more importantly,
can distinguish between can distinguish between
relative units (months and years) and quantitative units (days, hours, etc). relative units (months and years) and quantitative units (days, hours, etc).
Instead, reltime Instead, reltime
must force months to be exactly 30 days, so time arithmetic does not must force months to be exactly 30 days, so time arithmetic does not
always work as expected. always work as expected.
For example, adding one reltime <literal>year</literal> to abstime <literal>today</literal> does not For example, adding one reltime <literal>year</literal> to
produce today's date one year from abstime <literal>today</literal> does not
now, but rather a date 360 days from today. produce today's date one year from
</para> now, but rather a date 360 days from today.
</para>
<para>
<type>reltime</type> shares input and output routines with the other <para>
time span types. <type>reltime</type> shares input and output routines with the other
The section on <type>timespan</type> covers this in more detail. time span types.
</para> The section on <type>timespan</type> covers this in more detail.
</para>
</sect2>
</sect2>
<sect2>
<title><type>timestamp</type></title> <sect2>
<title><type>timestamp</type></title>
<para>
This is currently a limited-range absolute time which closely resembles the <para>
abstime This is currently a limited-range absolute time which closely resembles the
data type. It shares the general input parser with the other date/time types. abstime
In future releases this type will absorb the capabilities of the data type. It shares the general input parser with the other date/time types.
<type>datetime</type> type In future releases this type will absorb the capabilities of the
and will move toward <acronym>SQL92</acronym> compliance. <type>datetime</type> type
</para> and will move toward <acronym>SQL92</acronym> compliance.
</para>
<para>
<type>timestamp</type> is specified using the same syntax as for <para>
<type>datetime</type>. <type>timestamp</type> is specified using the same syntax as for
</para> <type>datetime</type>.
</sect2> </para>
</sect2>
<sect2>
<title><type>interval</type></title> <sect2>
<title><type>interval</type></title>
<para>
<type>interval</type> is an <acronym>SQL92</acronym> data type which is <para>
currently mapped to the <type>timespan</type> <type>interval</type> is an <acronym>SQL92</acronym> data type which is
<productname>Postgres</productname> data type. currently mapped to the <type>timespan</type>
</para> <productname>Postgres</productname> data type.
</sect2> </para>
</sect2>
<sect2>
<title>tinterval</title> <sect2>
<title><type>tinterval</type></title>
<para>
Time ranges are specified as: <para>
Time ranges are specified as:
<programlisting>
<programlisting>
[ 'abstime' 'abstime'] [ 'abstime' 'abstime']
where where
abstime is a time in the absolute time format. abstime is a time in the absolute time format.
</programlisting> </programlisting>
Special abstime values such as Special abstime values such as
<literal>current', <literal>infinity' and <literal>-infinity' can be used.</literal></literal></literal> <literal>current</literal>, <literal>infinity</literal> and
</para></sect2> <literal>-infinity</literal> can be used.
</para>
</sect1> </sect2>
<sect1> </sect1>
<title>Boolean Type</title>
<sect1>
<para> <title>Boolean Type</title>
<productname>Postgres</productname> supports <type>bool</type> as
the <acronym>SQL3</acronym> boolean type. <para>
<type>bool</type> can have one of only two states: 'true' or 'false'. <productname>Postgres</productname> supports <type>bool</type> as
A third state, 'unknown', is not the <acronym>SQL3</acronym> boolean type.
implemented and is not suggested in <acronym>SQL3</acronym>; <type>bool</type> can have one of only two states: 'true' or 'false'.
<acronym>NULL</acronym> is an A third state, 'unknown', is not
effective substitute. <type>bool</type> can be used in any boolean expression, implemented and is not suggested in <acronym>SQL3</acronym>;
and boolean expressions <acronym>NULL</acronym> is an
always evaluate to a result compatible with this type.</para> effective substitute. <type>bool</type> can be used in any boolean expression,
and boolean expressions
<para> always evaluate to a result compatible with this type.</para>
<type>bool</type> uses 1 byte of storage.
</para> <para>
<type>bool</type> uses 1 byte of storage.
<para> </para>
<table tocentry="1">
<title><productname>Postgres</productname> Boolean Type</title> <para>
<titleabbrev>Booleans</titleabbrev> <table tocentry="1">
<tgroup cols="3"> <title><productname>Postgres</productname> Boolean Type</title>
<thead> <titleabbrev>Booleans</titleabbrev>
<tgroup cols="3">
<thead>
<row> <row>
<entry>State</entry> <entry>State</entry>
<entry>Output</entry> <entry>Output</entry>
<entry>Input</entry> <entry>Input</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>True</entry> <entry>True</entry>
<entry>'t'</entry> <entry>'t'</entry>
...@@ -1519,35 +1542,35 @@ always evaluate to a result compatible with this type.</para> ...@@ -1519,35 +1542,35 @@ always evaluate to a result compatible with this type.</para>
<entry>'f'</entry> <entry>'f'</entry>
<entry>FALSE, 'f', 'false', 'n', 'no', '0'</entry> <entry>FALSE, 'f', 'false', 'n', 'no', '0'</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Geometric Types</title> <title>Geometric Types</title>
<para> <para>
Geometric types represent two-dimensional spatial objects. Geometric types represent two-dimensional spatial objects.
The most fundamental type, 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>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname> Geometric Types</title> <title><productname>Postgres</productname> Geometric Types</title>
<titleabbrev>Geometrics</titleabbrev> <titleabbrev>Geometrics</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>Geometric Type</entry> <entry>Geometric Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Representation</entry> <entry>Representation</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>point</entry> <entry>point</entry>
<entry>16 bytes</entry> <entry>16 bytes</entry>
...@@ -1596,104 +1619,104 @@ the point, forms the basis for all of the other types. ...@@ -1596,104 +1619,104 @@ the point, forms the basis for all of the other types.
<entry><(x,y),r></entry> <entry><(x,y),r></entry>
<entry>Circle (center and radius)</entry> <entry>Circle (center and radius)</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<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 operations such as scaling, translation, rotation, and determining
intersections. intersections.
</para> </para>
<sect2> <sect2>
<title>Point</title> <title>Point</title>
<para> <para>
Points are the fundamental two-dimensional building block for geometric types. Points are the fundamental two-dimensional building block for geometric types.
</para> </para>
<para> <para>
<type>point</type> is specified using the following syntax: <type>point</type> is specified using the following syntax:
<programlisting> <programlisting>
( x , y ) ( x , y )
x , y x , y
where where
x is the x-axis coordinate as a floating point number x is the x-axis coordinate as a floating point number
y is the y-axis coordinate as a floating point number y is the y-axis coordinate as a floating point number
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Line Segment</title> <title>Line Segment</title>
<para> <para>
Line segments (lseg) are represented by pairs of points. Line segments (<type>lseg</type>) are represented by pairs of points.
</para> </para>
<para> <para>
<type>lseg</type> is specified using the following syntax: <type>lseg</type> is specified using the following syntax:
<programlisting> <programlisting>
( ( x1 , y1 ) , ( x2 , y2 ) ) ( ( x1 , y1 ) , ( x2 , y2 ) )
( x1 , y1 ) , ( x2 , y2 ) ( x1 , y1 ) , ( x2 , y2 )
x1 , y1 , x2 , y2 x1 , y1 , x2 , y2
where where
(x1,y1) and (x2,y2) are the endpoints of the segment (x1,y1) and (x2,y2) are the endpoints of the segment
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Box</title> <title>Box</title>
<para> <para>
Boxes are represented by pairs of points which are opposite Boxes are represented by pairs of points which are opposite
corners of the box. corners of the box.
</para> </para>
<para> <para>
<type>box</type> is specified using the following syntax: <type>box</type> is specified using the following syntax:
<programlisting> <programlisting>
( ( x1 , y1 ) , ( x2 , y2 ) ) ( ( x1 , y1 ) , ( x2 , y2 ) )
( x1 , y1 ) , ( x2 , y2 ) ( x1 , y1 ) , ( x2 , y2 )
x1 , y1 , x2 , y2 x1 , y1 , x2 , y2
where where
(x1,y1) and (x2,y2) are opposite corners (x1,y1) and (x2,y2) are opposite corners
</programlisting> </programlisting>
Boxes are output using the first syntax. Boxes are output using the first syntax.
The corners are reordered on input to store The corners are reordered on input to store
the lower left corner first and the upper right corner last. the lower left corner first and the upper right corner last.
Other corners of the box can be entered, but the lower Other corners of the box can be entered, but the lower
left and upper right corners are determined from the input and stored. left and upper right corners are determined from the input and stored.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Path</title> <title>Path</title>
<para> <para>
Paths are represented by connected sets of points. Paths can be "open", where Paths are represented by connected sets of points. Paths can be "open", where
the first and last points in the set are not connected, and "closed", the first and last points in the set are not connected, and "closed",
where the first and last point are connected. Functions where the first and last point are connected. Functions
<function>popen(p)</function> <function>popen(p)</function>
and and
<function>pclose(p)</function> <function>pclose(p)</function>
are supplied to force a path to be open or closed, and functions are supplied to force a path to be open or closed, and functions
<function>isopen(p)</function> <function>isopen(p)</function>
and and
<function>isclosed(p)</function> <function>isclosed(p)</function>
are supplied to select either type in a query. are supplied to select either type in a query.
</para> </para>
<para> <para>
path is specified using the following syntax: <type>path</type> is specified using the following syntax:
<programlisting> <programlisting>
( ( x1 , y1 ) , ... , ( xn , yn ) ) ( ( x1 , y1 ) , ... , ( xn , yn ) )
[ ( x1 , y1 ) , ... , ( xn , yn ) ] [ ( x1 , y1 ) , ... , ( xn , yn ) ]
( x1 , y1 ) , ... , ( xn , yn ) ( x1 , y1 ) , ... , ( xn , yn )
...@@ -1703,60 +1726,61 @@ where ...@@ -1703,60 +1726,61 @@ where
(x1,y1),...,(xn,yn) are points 1 through n (x1,y1),...,(xn,yn) are points 1 through n
a leading "[" indicates an open path a leading "[" indicates an open path
a leading "(" indicates a closed path a leading "(" indicates a closed path
</programlisting> </programlisting>
Paths are output using the first syntax.
Note that <productname>Postgres</productname> versions prior to Paths are output using the first syntax.
v6.1 used a format for paths which had a single leading parenthesis, Note that <productname>Postgres</productname> versions prior to
a "closed" flag, v6.1 used a format for paths which had a single leading parenthesis,
an integer count of the number of points, then the list of points followed by a a "closed" flag,
closing parenthesis. an integer count of the number of points, then the list of points followed by a
The built-in function <function>upgradepath</function> is supplied to convert closing parenthesis.
paths dumped and reloaded from pre-v6.1 databases. The built-in function <function>upgradepath</function> is supplied to convert
</para> paths dumped and reloaded from pre-v6.1 databases.
</sect2> </para>
</sect2>
<sect2>
<title>Polygon</title> <sect2>
<title>Polygon</title>
<para>
Polygons are represented by sets of points. Polygons should probably be <para>
considered equivalent to closed paths, but are stored differently Polygons are represented by sets of points. Polygons should probably be
and have their own set of support routines. considered equivalent to closed paths, but are stored differently
</para> and have their own set of support routines.
</para>
<para>
<type>polygon</type> is specified using the following syntax: <para>
<type>polygon</type> is specified using the following syntax:
<programlisting>
<programlisting>
( ( x1 , y1 ) , ... , ( xn , yn ) ) ( ( x1 , y1 ) , ... , ( xn , yn ) )
( x1 , y1 ) , ... , ( xn , yn ) ( x1 , y1 ) , ... , ( xn , yn )
( x1 , y1 , ... , xn , yn ) ( x1 , y1 , ... , xn , yn )
x1 , y1 , ... , xn , yn x1 , y1 , ... , xn , yn
where where
(x1,y1),...,(xn,yn) are points 1 through n (x1,y1),...,(xn,yn) are points 1 through n
</programlisting> </programlisting>
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, of x-axis coordinates, the list of y-axis coordinates,
followed by a closing parenthesis. 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>
</sect2> </sect2>
<sect2> <sect2>
<title>Circle</title> <title>Circle</title>
<para> <para>
Circles are represented by a center point and a radius. Circles are represented by a center point and a radius.
</para> </para>
<para> <para>
circle is specified using the following syntax: <type>circle</type> is specified using the following syntax:
<programlisting> <programlisting>
< ( x , y ) , r > < ( x , y ) , r >
( ( x , y ) , r ) ( ( x , y ) , r )
( x , y ) , r ( x , y ) , r
...@@ -1764,38 +1788,38 @@ circle is specified using the following syntax: ...@@ -1764,38 +1788,38 @@ circle is specified using the following syntax:
where where
(x,y) is the center of the circle (x,y) is the center of the circle
r is the radius of the circle r is the radius of the circle
</programlisting> </programlisting>
Circles are output using the first syntax. Circles are output using the first syntax.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
<sect1> <sect1>
<title>IP Version 4 Networks and Host Addresses</title> <title>IP Version 4 Networks and Host Addresses</title>
<para> <para>
The <type>cidr</type> type stores networks specified The <type>cidr</type> type stores networks specified
in <acronym>CIDR</acronym> (Classless Inter-Domain Routing) notation. in <acronym>CIDR</acronym> (Classless Inter-Domain Routing) notation.
The <type>inet</type> type stores hosts and networks in CIDR notation using a simple The <type>inet</type> type stores hosts and networks in CIDR notation using a simple
variation in representation to represent simple host TCP/IP addresses. variation in representation to represent simple host TCP/IP addresses.
</para> </para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname>IP Version 4 Types</title> <title><productname>Postgres</productname>IP Version 4 Types</title>
<titleabbrev>IPV4</titleabbrev> <titleabbrev>IPV4</titleabbrev>
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
<entry>IPV4 Type</entry> <entry>IPV4 Type</entry>
<entry>Storage</entry> <entry>Storage</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Range</entry> <entry>Range</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>cidr</entry> <entry>cidr</entry>
<entry>variable</entry> <entry>variable</entry>
...@@ -1808,26 +1832,29 @@ variation in representation to represent simple host TCP/IP addresses. ...@@ -1808,26 +1832,29 @@ variation in representation to represent simple host TCP/IP addresses.
<entry>nets and hosts</entry> <entry>nets and hosts</entry>
<entry>Valid IPV4 CIDR blocks</entry> <entry>Valid IPV4 CIDR blocks</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para> </para>
<sect2> <sect2>
<title>CIDR</title> <title>CIDR</title>
<para> <para>
The <type>cidr</type> type holds a CIDR network. The <type>cidr</type> type holds a CIDR network.
The format for specifying classless networks is <replaceable class="parameter">x.x.x.x/y</replaceable> The format for specifying classless networks is
<replaceable class="parameter">x.x.x.x/y</replaceable>
where <replaceable class="parameter">x.x.x.x</replaceable> is the where <replaceable class="parameter">x.x.x.x</replaceable> is the
network and <replaceable class="parameter">/y</replaceable> is the number of bits in the netmask. network and <replaceable class="parameter">/y</replaceable> is
If <replaceable class="parameter">/y</replaceable> omitted, it is calculated using assumptions from the number of bits in the netmask.
the older classfull naming system except that it is extended to include at least If <replaceable class="parameter">/y</replaceable> omitted, it is
all of the octets in the input. calculated using assumptions from
</para> the older classfull naming system except that it is extended to include at least
all of the octets in the input.
</para>
<para> <para>
Here are some examples: Here are some examples:
<table tocentry="1"> <table tocentry="1">
<title><productname>Postgres</productname>IP Types Examples</title> <title><productname>Postgres</productname>IP Types Examples</title>
...@@ -1880,32 +1907,34 @@ Here are some examples: ...@@ -1880,32 +1907,34 @@ Here are some examples:
<sect2> <sect2>
<title id="inet-type"><type>inet</type></title> <title id="inet-type"><type>inet</type></title>
<para> <para>
The <type>inet</type> type is designed to hold, in one field, all of the information The <type>inet</type> type is designed to hold, in one field, all of the information
about a host including the CIDR-style subnet that it is in. about a host including the CIDR-style subnet that it is in.
Note that if you want to store proper CIDR networks, Note that if you want to store proper CIDR networks,
you should use the <type>cidr</type> type. you should use the <type>cidr</type> type.
The <type>inet</type> type is similar to the <type>cidr</type> type except that the bits in the The <type>inet</type> type is similar to the <type>cidr</type>
host part can be non-zero. type except that the bits in the
Functions exist to extract the various elements of the field. host part can be non-zero.
</para> Functions exist to extract the various elements of the field.
</para>
<para>
<para>
The input format for this function is The input format for this function is
<replaceable class="parameter">x.x.x.x/y</replaceable> <replaceable class="parameter">x.x.x.x/y</replaceable>
where <replaceable class="parameter">x.x.x.x</replaceable> is where <replaceable class="parameter">x.x.x.x</replaceable> is
an internet host and <replaceable class="parameter">y</replaceable> an internet host and <replaceable class="parameter">y</replaceable>
is the number of bits in the netmask. is the number of bits in the netmask.
If the <replaceable class="parameter">/y</replaceable> part is left off, If the <replaceable class="parameter">/y</replaceable> part is left off,
it is treated as <literal>/32</literal>. it is treated as <literal>/32</literal>.
On output, the <replaceable class="parameter">/y</replaceable> part is not printed On output, the <replaceable class="parameter">/y</replaceable> part is not printed
if it is <literal>/32</literal>. if it is <literal>/32</literal>.
This allows the type to be used as a straight host type by just leaving off This allows the type to be used as a straight host type by just leaving off
the bits part. the bits part.
</para></sect2> </para>
</sect1> </sect2>
</sect1>
</chapter>
</chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment