rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/datatype.sgml

3869 lines
132 KiB
Plaintext
Raw Normal View History

Tsearch2 functionality migrates to core. The bulk of this work is by Oleg Bartunov and Teodor Sigaev, but I did a lot of editorializing, so anything that's broken is probably my fault. Documentation is nonexistent as yet, but let's land the patch so we can get some portability testing done.
2007-08-21 03:11:32 +02:00
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.207 2007/08/21 01:11:11 tgl Exp $ -->
Minor markup changes. Refer to (".../catalog") in the emacs hints.
2000-03-31 05:27:42 +02:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<chapter id="datatype">
Minor updates for release.
1999-06-14 09:36:12 +02:00
<title id="datatype-title">Data Types</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype">
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>data type</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>type</primary>
<see>data type</see>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<para>
Merge some user-submitted suggestions for improvement into the documentation. Mostly add some <xref>s, fix a few typos, and document that zlib is required in the installation docs.
2005-10-15 03:47:12 +02:00
<productname>PostgreSQL</productname> has a rich set of native data
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
types available to users. Users can add new types to
Merge some user-submitted suggestions for improvement into the documentation. Mostly add some <xref>s, fix a few typos, and document that zlib is required in the installation docs.
2005-10-15 03:47:12 +02:00
<productname>PostgreSQL</productname> using the <xref
linkend="sql-createtype" endterm="sql-createtype-title"> command.
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</para>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<para>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<xref linkend="datatype-table"> shows all the built-in general-purpose data
types. Most of the alternative names listed in the
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<quote>Aliases</quote> column are the names used internally by
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> for historical reasons. In
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
addition, some internally used or deprecated types are available,
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
but they are not listed here.
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</para>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<table id="datatype-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Data Types</title>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<tgroup cols="3">
<thead>
<row>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Name</entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>Aliases</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry>Description</entry>
</row>
</thead>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<tbody>
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>bigint</type></entry>
<entry><type>int8</type></entry>
<entry>signed eight-byte integer</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<row>
<entry><type>bigserial</type></entry>
<entry><type>serial8</type></entry>
<entry>autoincrementing eight-byte integer</entry>
</row>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Now that I look, table 8-1 has some other marginal misstatements in it. If we're going to put brackets around optional precision specs in some entries, we'd better do it in all.
2004-09-20 06:19:50 +02:00
<entry><type>bit [ (<replaceable>n</replaceable>) ]</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>fixed-length bit string</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Now that I look, table 8-1 has some other marginal misstatements in it. If we're going to put brackets around optional precision specs in some entries, we'd better do it in all.
2004-09-20 06:19:50 +02:00
<entry><type>bit varying [ (<replaceable>n</replaceable>) ]</type></entry>
<entry><type>varbit</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>variable-length bit string</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>boolean</type></entry>
<entry><type>bool</type></entry>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<entry>logical Boolean (true/false)</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>box</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>rectangular box in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Add mention of bytea data type and escaping rules.
2001-09-04 05:17:54 +02:00
<row>
<entry><type>bytea</type></entry>
<entry></entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry>binary data (<quote>byte array</>)</entry>
Add mention of bytea data type and escaping rules.
2001-09-04 05:17:54 +02:00
</row>
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
<row>
Now that I look, table 8-1 has some other marginal misstatements in it. If we're going to put brackets around optional precision specs in some entries, we'd better do it in all.
2004-09-20 06:19:50 +02:00
<entry><type>character varying [ (<replaceable>n</replaceable>) ]</type></entry>
<entry><type>varchar [ (<replaceable>n</replaceable>) ]</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>variable-length character string</entry>
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<row>
Now that I look, table 8-1 has some other marginal misstatements in it. If we're going to put brackets around optional precision specs in some entries, we'd better do it in all.
2004-09-20 06:19:50 +02:00
<entry><type>character [ (<replaceable>n</replaceable>) ]</type></entry>
<entry><type>char [ (<replaceable>n</replaceable>) ]</type></entry>
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<entry>fixed-length character string</entry>
</row>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>cidr</type></entry>
<entry></entry>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<entry>IPv4 or IPv6 network address</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>circle</type></entry>
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>circle in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>date</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>calendar date (year, month, day)</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>double precision</type></entry>
<entry><type>float8</type></entry>
<entry>double precision floating-point number</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>inet</type></entry>
<entry></entry>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<entry>IPv4 or IPv6 host address</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>integer</type></entry>
<entry><type>int</type>, <type>int4</type></entry>
<entry>signed four-byte integer</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<row>
Now that I look, table 8-1 has some other marginal misstatements in it. If we're going to put brackets around optional precision specs in some entries, we'd better do it in all.
2004-09-20 06:19:50 +02:00
<entry><type>interval [ (<replaceable>p</replaceable>) ]</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>time span</entry>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>line</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry>infinite line in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>lseg</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>line segment in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>macaddr</type></entry>
<entry></entry>
<entry>MAC address</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>money</type></entry>
<entry></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>currency amount</entry>
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Document the precision arguments for date/time types per SQL9x. Update the list of recognized time zones. Document the range of arguments allowed for SET TIME ZONE. Still need to add info on other date/time symbols (e.g. "AM", "T") and to freshen the docs on the date/time parsing rules.
2001-12-29 19:35:54 +01:00
<entry><type>numeric [ (<replaceable>p</replaceable>,
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<replaceable>s</replaceable>) ]</type></entry>
Document the precision arguments for date/time types per SQL9x. Update the list of recognized time zones. Document the range of arguments allowed for SET TIME ZONE. Still need to add info on other date/time symbols (e.g. "AM", "T") and to freshen the docs on the date/time parsing rules.
2001-12-29 19:35:54 +01:00
<entry><type>decimal [ (<replaceable>p</replaceable>,
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<replaceable>s</replaceable>) ]</type></entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry>exact numeric of selectable precision</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>path</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry>geometric path in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>point</type></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>geometric point in the plane</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Documentation updates to reflect TOAST and new-style fmgr.
2000-08-25 01:36:29 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>polygon</type></entry>
Documentation updates to reflect TOAST and new-style fmgr.
2000-08-25 01:36:29 +02:00
<entry></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>closed geometric path in the plane</entry>
Documentation updates to reflect TOAST and new-style fmgr.
2000-08-25 01:36:29 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>real</type></entry>
<entry><type>float4</type></entry>
<entry>single precision floating-point number</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>smallint</type></entry>
<entry><type>int2</type></entry>
<entry>signed two-byte integer</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>serial</type></entry>
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
<entry><type>serial4</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>autoincrementing four-byte integer</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry><type>text</type></entry>
<entry></entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<entry>variable-length character string</entry>
</row>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
<entry><type>time [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry></entry>
<entry>time of day</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
<entry><type>time [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
proof-reading
2001-11-28 21:49:10 +01:00
<entry><type>timetz</type></entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<entry>time of day, including time zone</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
<row>
Put the brackets in the right places in timestamp entries in table 8-1. Spotted by Josh Purinton.
2004-09-18 17:28:03 +02:00
<entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry></entry>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
<entry>date and time</entry>
</row>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<row>
Put the brackets in the right places in timestamp entries in table 8-1. Spotted by Josh Purinton.
2004-09-18 17:28:03 +02:00
<entry><type>timestamp [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
proof-reading
2001-11-28 21:49:10 +01:00
<entry><type>timestamptz</type></entry>
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
<entry>date and time, including time zone</entry>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</row>
Initial SQL/XML support: xml data type and initial set of functions.
2006-12-21 17:05:16 +01:00
Documentation for UUID type
2007-04-20 23:51:46 +02:00
<row>
<entry><type>uuid</type></entry>
<entry></entry>
<entry>universally unique identifier</entry>
</row>
Initial SQL/XML support: xml data type and initial set of functions.
2006-12-21 17:05:16 +01:00
<row>
<entry><type>xml</type></entry>
<entry></entry>
<entry>XML data</entry>
</row>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
</tbody>
</tgroup>
</table>
Include new cidr and inet data types.
1998-10-27 07:14:41 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<note>
<title>Compatibility</title>
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
The following types (or spellings thereof) are specified by
Update conformance information about bigint type found by Michael Glaesemann
2007-07-27 12:37:52 +02:00
<acronym>SQL</acronym>: <type>bigint</type>, <type>bit</type>, <type>bit
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
varying</type>, <type>boolean</type>, <type>char</type>,
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<type>character varying</type>, <type>character</type>,
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
<type>varchar</type>, <type>date</type>, <type>double
precision</type>, <type>integer</type>, <type>interval</type>,
<type>numeric</type>, <type>decimal</type>, <type>real</type>,
Minor copy-editing.
2003-11-06 23:21:47 +01:00
<type>smallint</type>, <type>time</type> (with or without time zone),
Initial SQL/XML support: xml data type and initial set of functions.
2006-12-21 17:05:16 +01:00
<type>timestamp</type> (with or without time zone),
<type>xml</type>.
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</para>
</note>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<para>
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
Each data type has an external representation determined by its input
and output functions. Many of the built-in types have
obvious external formats. However, several types are either unique
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
to <productname>PostgreSQL</productname>, such as geometric
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
paths, or have several possibilities for formats, such as the date
and time types.
Some of the input and output functions are not invertible. That is,
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
the result of an output function might lose accuracy when compared to
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
the original input.
</para>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-numeric">
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<title>Numeric Types</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-numeric">
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>data type</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<secondary>numeric</secondary>
</indexterm>
Include mention of CASE, COALESCE, and IFNULL. Add date/time parsing procedure (perhaps should be in appendix). Add time zone information (ditto). Update keyword list.
1999-05-12 09:32:47 +02:00
<para>
Documentation updates to reflect TOAST and new-style fmgr.
2000-08-25 01:36:29 +02:00
Numeric types consist of two-, four-, and eight-byte integers,
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
four- and eight-byte floating-point numbers, and selectable-precision
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
decimals. <xref linkend="datatype-numeric-table"> lists the
available types.
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</para>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-numeric-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Numeric Types</title>
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 :()
1999-08-06 15:43:42 +02:00
<tgroup cols="4">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
<entry>Description</entry>
<entry>Range</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<tbody>
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>smallint</></entry>
<entry>2 bytes</entry>
<entry>small-range integer</entry>
<entry>-32768 to +32767</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>integer</></entry>
<entry>4 bytes</entry>
<entry>usual choice for integer</entry>
<entry>-2147483648 to +2147483647</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>bigint</></entry>
<entry>8 bytes</entry>
<entry>large-range integer</entry>
<entry>-9223372036854775808 to 9223372036854775807</entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>decimal</></entry>
<entry>variable</entry>
<entry>user-specified precision, exact</entry>
<entry>no limit</entry>
Update for NUMERIC/DECIMAL data type.
1999-10-13 04:44:23 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>numeric</></entry>
<entry>variable</entry>
<entry>user-specified precision, exact</entry>
<entry>no limit</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>real</></entry>
<entry>4 bytes</entry>
<entry>variable-precision, inexact</entry>
<entry>6 decimal digits precision</entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>double precision</></entry>
<entry>8 bytes</entry>
<entry>variable-precision, inexact</entry>
<entry>15 decimal digits precision</entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</row>
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 :()
1999-08-06 15:43:42 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>serial</></entry>
<entry>4 bytes</entry>
<entry>autoincrementing integer</entry>
<entry>1 to 2147483647</entry>
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>bigserial</type></entry>
<entry>8 bytes</entry>
<entry>large autoincrementing integer</entry>
<entry>1 to 9223372036854775807</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</tbody>
</tgroup>
</table>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
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 :()
1999-08-06 15:43:42 +02:00
<para>
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
The syntax of constants for the numeric types is described in
<xref linkend="sql-syntax-constants">. The numeric types have a
full set of corresponding arithmetic operators and
functions. Refer to <xref linkend="functions"> for more
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
information. The following sections describe the types in detail.
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 :()
1999-08-06 15:43:42 +02:00
</para>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<sect2 id="datatype-int">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Integer Types</title>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm zone="datatype-int">
<primary>integer</primary>
</indexterm>
<indexterm zone="datatype-int">
<primary>smallint</primary>
</indexterm>
<indexterm zone="datatype-int">
<primary>bigint</primary>
</indexterm>
<indexterm>
<primary>int4</primary>
<see>integer</see>
</indexterm>
<indexterm>
<primary>int2</primary>
<see>smallint</see>
</indexterm>
<indexterm>
<primary>int8</primary>
<see>bigint</see>
</indexterm>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The types <type>smallint</type>, <type>integer</type>, and
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<type>bigint</type> store whole numbers, that is, numbers without
fractional components, of various ranges. Attempts to store
values outside of the allowed range will result in an error.
</para>
<para>
The type <type>integer</type> is the usual choice, as it offers
the best balance between range, storage size, and performance.
The <type>smallint</type> type is generally only used if disk
space is at a premium. The <type>bigint</type> type should only
be used if the <type>integer</type> range is not sufficient,
because the latter is definitely faster.
</para>
<para>
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
The <type>bigint</type> type might not function correctly on all
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
platforms, since it relies on compiler support for eight-byte
integers. On a machine without such support, <type>bigint</type>
acts the same as <type>integer</type> (but still takes up eight
bytes of storage). However, we are not aware of any reasonable
platform where this is actually the case.
</para>
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
<acronym>SQL</acronym> only specifies the integer types
Update conformance information about bigint type found by Michael Glaesemann
2007-07-27 12:37:52 +02:00
<type>integer</type> (or <type>int</type>),
<type>smallint</type>, and <type>bigint</type>. The
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
type names <type>int2</type>, <type>int4</type>, and
<type>int8</type> are extensions, which are shared with various
other <acronym>SQL</acronym> database systems.
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
</para>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</sect2>
<sect2 id="datatype-numeric-decimal">
<title>Arbitrary Precision Numbers</title>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>numeric (data type)</primary>
</indexterm>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<indexterm>
<primary>arbitrary precision numbers</primary>
</indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm>
<primary>decimal</primary>
<see>numeric</see>
</indexterm>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The type <type>numeric</type> can store numbers with up to 1000
Mention precision of NUMERIC in docs.
2002-04-13 03:35:09 +02:00
digits of precision and perform calculations exactly. It is
especially recommended for storing monetary amounts and other
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
quantities where exactness is required. However, arithmetic on
<type>numeric</type> values is very slow compared to the integer
types, or to the floating-point types described in the next section.
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</para>
<para>
In what follows we use these terms: The
<firstterm>scale</firstterm> of a <type>numeric</type> is the
count of decimal digits in the fractional part, to the right of
the decimal point. The <firstterm>precision</firstterm> of a
<type>numeric</type> is the total count of significant digits in
the whole number, that is, the number of digits to both sides of
the decimal point. So the number 23.5141 has a precision of 6
and a scale of 4. Integers can be considered to have a scale of
zero.
</para>
<para>
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
Both the maximum precision and the maximum scale of a
<type>numeric</type> column can be
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
configured. To declare a column of type <type>numeric</type> use
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
the syntax:
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<programlisting>
NUMERIC(<replaceable>precision</replaceable>, <replaceable>scale</replaceable>)
</programlisting>
The precision must be positive, the scale zero or positive.
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
Alternatively:
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<programlisting>
NUMERIC(<replaceable>precision</replaceable>)
</programlisting>
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
selects a scale of 0. Specifying:
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<programlisting>
NUMERIC
</programlisting>
Tweak parser so that there is a defined representation for datatypes bpchar, bit, numeric with typmod -1. Alter format_type so that this representation is printed when the typmod is -1. This ensures that tables having such columns can be pg_dump'd and reloaded correctly. Also, remove the rather useless and non-SQL-compliant default precision and scale for type NUMERIC. A numeric column declared as such (with no precision/scale) will now have typmod -1 which means that numeric values of any precision/scale can be stored in it, without conversion to a uniform scale. This seems significantly more useful than the former behavior. Part of response to bug #513.
2001-11-12 22:04:46 +01:00
without any precision or scale creates a column in which numeric
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
values of any precision and scale can be stored, up to the
implementation limit on precision. A column of this kind will
not coerce input values to any particular scale, whereas
<type>numeric</type> columns with a declared scale will coerce
input values to that scale. (The <acronym>SQL</acronym> standard
requires a default scale of 0, i.e., coercion to integer
precision. We find this a bit useless. If you're concerned
about portability, always specify the precision and scale
explicitly.)
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</para>
<para>
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
If the scale of a value to be stored is greater than the declared
scale of the column, the system will round the value to the specified
number of fractional digits. Then, if the number of digits to the
left of the decimal point exceeds the declared precision minus the
declared scale, an error is raised.
</para>
<para>
Numeric values are physically stored without any extra leading or
trailing zeroes. Thus, the declared precision and scale of a column
are maximums, not fixed allocations. (In this sense the <type>numeric</>
type is more akin to <type>varchar(<replaceable>n</>)</type>
Mention the actual stored size of NUMERIC values, per David Fetter.
2005-05-01 17:54:46 +02:00
than to <type>char(<replaceable>n</>)</type>.) The actual storage
requirement is two bytes for each group of four decimal digits,
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
plus five to eight bytes overhead.
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</para>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<indexterm>
<primary>NaN</primary>
<see>not a number</see>
</indexterm>
<indexterm>
<primary>not a number</primary>
<secondary>numeric (data type)</secondary>
</indexterm>
Some editorializing on the docs for the dollar-quoting feature: fix grammar, don't drop discussions into the middle of unrelated discussions, etc.
2004-09-21 00:48:29 +02:00
<para>
In addition to ordinary numeric values, the <type>numeric</type>
type allows the special value <literal>NaN</>, meaning
<quote>not-a-number</quote>. Any operation on <literal>NaN</>
yields another <literal>NaN</>. When writing this value
as a constant in a SQL command, you must put quotes around it,
for example <literal>UPDATE table SET x = 'NaN'</>. On input,
the string <literal>NaN</> is recognized in a case-insensitive manner.
</para>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<note>
<para>
In most implementations of the <quote>not-a-number</> concept,
<literal>NaN</> is not considered equal to any other numeric
value (including <literal>NaN</>). In order to allow
<type>numeric</> values to be sorted and used in tree-based
indexes, <productname>PostgreSQL</> treats <literal>NaN</>
values as equal, and greater than all non-<literal>NaN</>
values.
</para>
</note>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<para>
The types <type>decimal</type> and <type>numeric</type> are
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
equivalent. Both types are part of the <acronym>SQL</acronym>
standard.
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</para>
</sect2>
<sect2 id="datatype-float">
Editorial review
2002-01-07 03:29:15 +01:00
<title>Floating-Point Types</title>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm zone="datatype-float">
<primary>real</primary>
</indexterm>
<indexterm zone="datatype-float">
<primary>double precision</primary>
</indexterm>
<indexterm>
<primary>float4</primary>
<see>real</see>
</indexterm>
<indexterm>
<primary>float8</primary>
<see>double precision</see>
</indexterm>
<indexterm zone="datatype-float">
<primary>floating point</primary>
</indexterm>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<para>
The data types <type>real</type> and <type>double
Editorial review
2002-01-07 03:29:15 +01:00
precision</type> are inexact, variable-precision numeric types.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
In practice, these types are usually implementations of
<acronym>IEEE</acronym> Standard 754 for Binary Floating-Point
Arithmetic (single and double precision, respectively), to the
extent that the underlying processor, operating system, and
compiler support it.
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</para>
<para>
Inexact means that some values cannot be converted exactly to the
internal format and are stored as approximations, so that storing
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
and printing back out a value might show slight discrepancies.
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
Managing these errors and how they propagate through calculations
is the subject of an entire branch of mathematics and computer
science and will not be discussed further here, except for the
following points:
<itemizedlist>
<listitem>
<para>
If you require exact storage and calculations (such as for
monetary amounts), use the <type>numeric</type> type instead.
</para>
</listitem>
<listitem>
<para>
If you want to do complicated calculations with these types
for anything important, especially if you rely on certain
behavior in boundary cases (infinity, underflow), you should
evaluate the implementation carefully.
</para>
</listitem>
<listitem>
<para>
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
Comparing two floating-point values for equality might or might
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
not work as expected.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Make FLOAT(p) measure the precision p in bits, not decimal digits, to match the SQL standard. Document FLOAT and FLOAT(p) notations in datatype.sgml. Per recent pghackers discussion.
2003-06-18 01:12:36 +02:00
On most platforms, the <type>real</type> type has a range of at least
1E-37 to 1E+37 with a precision of at least 6 decimal digits. The
<type>double precision</type> type typically has a range of around
1E-307 to 1E+308 with a precision of at least 15 digits. Values that
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
are too large or too small will cause an error. Rounding might
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
take place if the precision of an input number is too high.
Numbers too close to zero that are not representable as distinct
from zero will cause an underflow error.
</para>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<indexterm>
<primary>not a number</primary>
<secondary>double precision</secondary>
</indexterm>
Some editorializing on the docs for the dollar-quoting feature: fix grammar, don't drop discussions into the middle of unrelated discussions, etc.
2004-09-21 00:48:29 +02:00
<para>
In addition to ordinary numeric values, the floating-point types
have several special values:
<literallayout>
<literal>Infinity</literal>
<literal>-Infinity</literal>
<literal>NaN</literal>
</literallayout>
These represent the IEEE 754 special values
<quote>infinity</quote>, <quote>negative infinity</quote>, and
<quote>not-a-number</quote>, respectively. (On a machine whose
floating-point arithmetic does not follow IEEE 754, these values
will probably not work as expected.) When writing these values
as constants in a SQL command, you must put quotes around them,
for example <literal>UPDATE table SET x = 'Infinity'</>. On input,
these strings are recognized in a case-insensitive manner.
</para>
Add a note to the docs describing NaN's equality and ordering behavior. Per recent -hackers thread, this is noteworthy because Postgres behaves differently from most implementations of NaN, including IEEE754.
2007-01-14 23:37:59 +01:00
<note>
<para>
IEEE754 specifies that <literal>NaN</> should not compare equal
to any other floating-point value (including <literal>NaN</>).
In order to allow floating-point values to be sorted and used
in tree-based indexes, <productname>PostgreSQL</> treats
<literal>NaN</> values as equal, and greater than all
non-<literal>NaN</> values.
</para>
</note>
Make FLOAT(p) measure the precision p in bits, not decimal digits, to match the SQL standard. Document FLOAT and FLOAT(p) notations in datatype.sgml. Per recent pghackers discussion.
2003-06-18 01:12:36 +02:00
<para>
<productname>PostgreSQL</productname> also supports the SQL-standard
notations <type>float</type> and
<type>float(<replaceable>p</replaceable>)</type> for specifying
inexact numeric types. Here, <replaceable>p</replaceable> specifies
the minimum acceptable precision in binary digits.
<productname>PostgreSQL</productname> accepts
<type>float(1)</type> to <type>float(24)</type> as selecting the
<type>real</type> type, while
<type>float(25)</type> to <type>float(53)</type> select
<type>double precision</type>. Values of <replaceable>p</replaceable>
outside the allowed range draw an error.
<type>float</type> with no precision specified is taken to mean
<type>double precision</type>.
</para>
<note>
<para>
Prior to <productname>PostgreSQL</productname> 7.4, the precision in
<type>float(<replaceable>p</replaceable>)</type> was taken to mean
so many decimal digits. This has been corrected to match the SQL
standard, which specifies that the precision is measured in binary
digits. The assumption that <type>real</type> and
<type>double precision</type> have exactly 24 and 53 bits in the
mantissa respectively is correct for IEEE-standard floating point
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
implementations. On non-IEEE platforms it might be off a little, but
Make FLOAT(p) measure the precision p in bits, not decimal digits, to match the SQL standard. Document FLOAT and FLOAT(p) notations in datatype.sgml. Per recent pghackers discussion.
2003-06-18 01:12:36 +02:00
for simplicity the same ranges of <replaceable>p</replaceable> are used
on all platforms.
</para>
</note>
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</sect2>
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 :()
1999-08-06 15:43:42 +02:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-serial">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Serial Types</title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-serial">
<primary>serial</primary>
</indexterm>
Grammatical corrections.
2001-10-30 21:13:44 +01:00
<indexterm zone="datatype-serial">
<primary>bigserial</primary>
</indexterm>
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
<indexterm zone="datatype-serial">
<primary>serial4</primary>
</indexterm>
<indexterm zone="datatype-serial">
<primary>serial8</primary>
</indexterm>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>auto-increment</primary>
<see>serial</see>
</indexterm>
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>sequence</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<secondary>and serial type</secondary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The data types <type>serial</type> and <type>bigserial</type>
are not true types, but merely
Minor copy-editing.
2003-10-16 06:52:21 +02:00
a notational convenience for setting up unique identifier columns
This patch improves the documentation for SERIAL columns a little bit. Neil Conway
2002-12-06 06:17:42 +01:00
(similar to the <literal>AUTO_INCREMENT</literal> property
supported by some other databases). In the current
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
implementation, specifying:
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 :()
1999-08-06 15:43:42 +02:00
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<programlisting>
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
<replaceable class="parameter">colname</replaceable> SERIAL
);
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</programlisting>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
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 :()
1999-08-06 15:43:42 +02:00
is equivalent to specifying:
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
<programlisting>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq;
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
<replaceable class="parameter">colname</replaceable> integer NOT NULL DEFAULT nextval('<replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq')
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
);
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq OWNED BY <replaceable class="parameter">tablename</replaceable>.<replaceable class="parameter">colname</replaceable>;
Start adding some more documentation about the number types. Make bigserial and alias for serial8 for consistency with bigint/int8.
2001-08-24 22:03:45 +02:00
</programlisting>
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 :()
1999-08-06 15:43:42 +02:00
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
Thus, we have created an integer column and arranged for its default
Fix pg_dump to dump serial columns as serials. Per pghackers discussion, cause SERIAL column declaration not to imply UNIQUE, so that this can be done without creating an extra index.
2002-08-19 21:33:36 +02:00
values to be assigned from a sequence generator. A <literal>NOT NULL</>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
constraint is applied to ensure that a null value cannot be explicitly
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
inserted, either. (In most cases you would also want to attach a
Fix pg_dump to dump serial columns as serials. Per pghackers discussion, cause SERIAL column declaration not to imply UNIQUE, so that this can be done without creating an extra index.
2002-08-19 21:33:36 +02:00
<literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint to prevent
duplicate values from being inserted by accident, but this is
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
not automatic.) Lastly, the sequence is marked as <quote>owned by</>
the column, so that it will be dropped if the column or table is dropped.
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
</para>
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<note>
<para>
Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type>
implied <literal>UNIQUE</literal>. This is no longer automatic. If
you wish a serial column to be in a unique constraint or a
primary key, it must now be specified, same as with
any other data type.
</para>
</note>
This patch improves the documentation for SERIAL columns a little bit. Neil Conway
2002-12-06 06:17:42 +01:00
<para>
Minor copy-editing.
2003-10-16 06:52:21 +02:00
To insert the next value of the sequence into the <type>serial</type>
column, specify that the <type>serial</type>
column should be assigned its default value. This can be done
either by excluding the column from the list of columns in
This patch improves the documentation for SERIAL columns a little bit. Neil Conway
2002-12-06 06:17:42 +01:00
the <command>INSERT</command> statement, or through the use of
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
the <literal>DEFAULT</literal> key word.
This patch improves the documentation for SERIAL columns a little bit. Neil Conway
2002-12-06 06:17:42 +01:00
</para>
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
<para>
The type names <type>serial</type> and <type>serial4</type> are
equivalent: both create <type>integer</type> columns. The type
Grammatical corrections.
2001-10-30 21:13:44 +01:00
names <type>bigserial</type> and <type>serial8</type> work just
the same way, except that they create a <type>bigint</type>
column. <type>bigserial</type> should be used if you anticipate
This patch improves the documentation for SERIAL columns a little bit. Neil Conway
2002-12-06 06:17:42 +01:00
the use of more than 2<superscript>31</> identifiers over the
lifetime of the table.
Sequences are now based on int8, not int4, arithmetic. SERIAL pseudo-type has an alias SERIAL4 and a sister SERIAL8. SERIAL8 is just the same except the created column is type int8 not int4. initdb forced. Note this also breaks any chance of pg_upgrade from 7.1, unless we hack up pg_upgrade to drop and recreate sequences. (Which is not out of the question, but I don't wanna do it.)
2001-08-16 22:38:56 +02:00
</para>
<para>
Minor copy-editing.
2003-10-16 06:52:21 +02:00
The sequence created for a <type>serial</type> column is
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
automatically dropped when the owning column is dropped.
You can drop the sequence without dropping the column, but this
will force removal of the column default expression.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
</sect1>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-money">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Monetary Types</title>
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 :()
1999-08-06 15:43:42 +02:00
<note>
<para>
minor copy editing
2001-03-25 00:03:26 +01:00
The <type>money</type> type is deprecated. Use
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
<type>numeric</type> or <type>decimal</type> instead, in
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
combination with the <function>to_char</function> function.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</note>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The <type>money</type> type stores a currency amount with a fixed
fractional precision; see <xref
linkend="datatype-money-table">.
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
Input is accepted in a variety of formats, including integer and
Editorial review
2002-01-07 03:29:15 +01:00
floating-point literals, as well as <quote>typical</quote>
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
currency formatting, such as <literal>'$1,000.00'</literal>.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Output is generally in the latter form but depends on the locale.
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</para>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-money-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Monetary Types</title>
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 :()
1999-08-06 15:43:42 +02:00
<tgroup cols="4">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
<entry>Description</entry>
<entry>Range</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
<tbody>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>money</entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>8 bytes</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>currency amount</entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>-92233720368547758.08 to +92233720368547758.07</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</tbody>
</tgroup>
</table>
</sect1>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-character">
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 :()
1999-08-06 15:43:42 +02:00
<title>Character Types</title>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-character">
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>character string</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<secondary>data types</secondary>
</indexterm>
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>string</primary>
<see>character string</see>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm zone="datatype-character">
<primary>character</primary>
</indexterm>
<indexterm zone="datatype-character">
<primary>character varying</primary>
</indexterm>
<indexterm zone="datatype-character">
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<primary>text</primary>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
</indexterm>
<indexterm zone="datatype-character">
<primary>char</primary>
</indexterm>
<indexterm zone="datatype-character">
<primary>varchar</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-character-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Character Types</title>
some clarifications inspired by the DocNotes
2001-08-08 00:41:49 +02:00
<tgroup cols="2">
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 :()
1999-08-06 15:43:42 +02:00
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Description</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
<tbody>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>character varying(<replaceable>n</>)</type>, <type>varchar(<replaceable>n</>)</type></entry>
<entry>variable-length with limit</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>character(<replaceable>n</>)</type>, <type>char(<replaceable>n</>)</type></entry>
<entry>fixed-length, blank padded</entry>
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
</row>
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 :()
1999-08-06 15:43:42 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>text</type></entry>
<entry>variable unlimited length</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
Add mention of bytea data type and escaping rules.
2001-09-04 05:17:54 +02:00
</tbody>
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 :()
1999-08-06 15:43:42 +02:00
</tgroup>
</table>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<para>
<xref linkend="datatype-character-table"> shows the
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
general-purpose character types available in
<productname>PostgreSQL</productname>.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
<para>
<acronym>SQL</acronym> defines two primary character types:
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<type>character varying(<replaceable>n</>)</type> and
<type>character(<replaceable>n</>)</type>, where <replaceable>n</>
is a positive integer. Both of these types can store strings up to
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
<replaceable>n</> characters in length. An attempt to store a
longer string into a column of these types will result in an
error, unless the excess characters are all spaces, in which case
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
the string will be truncated to the maximum length. (This somewhat
bizarre exception is required by the <acronym>SQL</acronym>
standard.) If the string to be stored is shorter than the declared
length, values of type <type>character</type> will be space-padded;
values of type <type>character varying</type> will simply store the
shorter
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
string.
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 :()
1999-08-06 15:43:42 +02:00
</para>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Removes or minimizes some documentation mentions of backward compatibility for release 7.2 and earlier. I have not altered any mentions of release 7.3 or later. The release notes were not modified, so the changes are still documented, just not in the main docs.
2006-04-23 05:39:52 +02:00
<para>
If one explicitly casts a value to <type>character
varying(<replaceable>n</>)</type> or
<type>character(<replaceable>n</>)</type>, then an over-length
value will be truncated to <replaceable>n</> characters without
raising an error. (This too is required by the
<acronym>SQL</acronym> standard.)
</para>
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
<para>
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
The notations <type>varchar(<replaceable>n</>)</type> and
<type>char(<replaceable>n</>)</type> are aliases for <type>character
varying(<replaceable>n</>)</type> and
<type>character(<replaceable>n</>)</type>, respectively.
<type>character</type> without length specifier is equivalent to
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<type>character(1)</type>. If <type>character varying</type> is used
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
without length specifier, the type accepts strings of any size. The
latter is a <productname>PostgreSQL</> extension.
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
In addition, <productname>PostgreSQL</productname> provides the
Random copy-editing.
2003-11-04 10:55:39 +01:00
<type>text</type> type, which stores strings of any length.
Although the type <type>text</type> is not in the
<acronym>SQL</acronym> standard, several other SQL database
management systems have it as well.
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</para>
Make length() disregard trailing spaces in char(n) values, per discussion some time ago and recent patch from Gavin Sherry. Update documentation to point out that trailing spaces are insignificant in char(n).
2004-02-01 07:27:48 +01:00
<para>
Values of type <type>character</type> are physically padded
with spaces to the specified width <replaceable>n</>, and are
stored and displayed that way. However, the padding spaces are
treated as semantically insignificant. Trailing spaces are
disregarded when comparing two values of type <type>character</type>,
and they will be removed when converting a <type>character</type> value
to one of the other string types. Note that trailing spaces
<emphasis>are</> semantically significant in
<type>character varying</type> and <type>text</type> values.
</para>
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
<para>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
The storage requirement for a short string (up to 126 bytes) is 1 byte
plus the actual string, which includes the space padding in the case of
<type>character</type>. Longer strings have 4 bytes overhead instead
of 1. Long strings are compressed by the system automatically, so
the physical requirement on disk might be less. Very long values are also
stored in background tables so that they do not interfere with rapid
access to shorter column values. In any case, the longest
Add mention of TOAST storage for character columns.
2002-07-16 06:45:59 +02:00
possible character string that can be stored is about 1 GB. (The
maximum value that will be allowed for <replaceable>n</> in the data
type declaration is less than that. It wouldn't be very useful to
change this because with multibyte character encodings the number of
characters and bytes can be quite different anyway. If you desire to
store long strings with no specific upper limit, use
<type>text</type> or <type>character varying</type> without a length
specifier, rather than making up an arbitrary length limit.)
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</para>
<tip>
<para>
There are no performance differences between these three types,
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
apart from increased storage size when using the blank-padded
type, and a few extra cycles to check the length when storing into
a length-constrained column. While
<type>character(<replaceable>n</>)</type> has performance
Make length() disregard trailing spaces in char(n) values, per discussion some time ago and recent patch from Gavin Sherry. Update documentation to point out that trailing spaces are insignificant in char(n).
2004-02-01 07:27:48 +01:00
advantages in some other database systems, it has no such advantages in
<productname>PostgreSQL</productname>. In most situations
<type>text</type> or <type>character varying</type> should be used
instead.
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</para>
</tip>
some clarifications inspired by the DocNotes
2001-08-08 00:41:49 +02:00
<para>
Refer to <xref linkend="sql-syntax-strings"> for information about
the syntax of string literals, and to <xref linkend="functions">
Improve the locale and character set docs, add some <xref>s pointing to the character set docs where appropriate, and improve the postmaster reference page. Character set cross-refs suggested by Gavin Kistner.
2004-03-23 03:47:35 +01:00
for information about available operators and functions. The
database character set determines the character set used to store
textual values; for more information on character set support,
refer to <xref linkend="multibyte">.
some clarifications inspired by the DocNotes
2001-08-08 00:41:49 +02:00
</para>
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
<example>
<title>Using the character types</title>
<programlisting>
CREATE TABLE test1 (a character(4));
INSERT INTO test1 VALUES ('ok');
SELECT a, char_length(a) FROM test1; -- <co id="co.datatype-char">
<computeroutput>
a | char_length
------+-------------
Update char_length() example for new semantics.
2004-02-01 07:55:07 +01:00
ok | 2
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</computeroutput>
CREATE TABLE test2 (b varchar(5));
INSERT INTO test2 VALUES ('ok');
INSERT INTO test2 VALUES ('good ');
INSERT INTO test2 VALUES ('too long');
<computeroutput>ERROR: value too long for type character varying(5)</computeroutput>
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
SELECT b, char_length(b) FROM test2;
<computeroutput>
b | char_length
-------+-------------
ok | 2
good | 5
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
too l | 5
Make char(n) and varchar(n) types raise an error if the inserted string is too long. While I was adjusting the regression tests I moved the array things all into array.sql, to make things more manageable.
2001-05-21 18:54:46 +02:00
</computeroutput>
</programlisting>
<calloutlist>
<callout arearefs="co.datatype-char">
<para>
The <function>char_length</function> function is discussed in
<xref linkend="functions-string">.
</para>
</callout>
</calloutlist>
</example>
Remove disclaimer about exact numeric types. They work now!
1999-05-27 17:47:28 +02:00
<para>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
There are two other fixed-length character types in
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
<productname>PostgreSQL</productname>, shown in <xref
linkend="datatype-character-special-table">. The <type>name</type>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
type exists <emphasis>only</emphasis> for storage of identifiers
in the internal system catalogs and is not intended for use by the general user. Its
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
length is currently defined as 64 bytes (63 usable characters plus
terminator) but should be referenced using the constant
<symbol>NAMEDATALEN</symbol>. The length is set at compile time (and
is therefore adjustable for special uses); the default maximum
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
length might change in a future release. The type <type>"char"</type>
Reorder VARCHAR() to appear before CHAR() in docs.
2003-01-15 19:01:05 +01:00
(note the quotes) is different from <type>char(1)</type> in that it
only uses one byte of storage. It is internally used in the system
catalogs as a poor-man's enumeration type.
Remove disclaimer about exact numeric types. They work now!
1999-05-27 17:47:28 +02:00
</para>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-character-special-table">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Special Character Types</title>
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 :()
1999-08-06 15:43:42 +02:00
<tgroup cols="3">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
<entry>Description</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
<tbody>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>"char"</type></entry>
<entry>1 byte</entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>single-byte internal type</entry>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</row>
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 :()
1999-08-06 15:43:42 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>name</type></entry>
<entry>64 bytes</entry>
<entry>internal type for object names</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</tbody>
</tgroup>
</table>
</sect1>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<sect1 id="datatype-binary">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Binary Data Types</title>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm zone="datatype-binary">
<primary>binary data</primary>
</indexterm>
<indexterm zone="datatype-binary">
<primary>bytea</primary>
</indexterm>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
The <type>bytea</type> data type allows storage of binary strings;
see <xref linkend="datatype-binary-table">.
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-binary-table">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Binary Data Types</title>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<tgroup cols="3">
<thead>
<row>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
Spell-check and markup police
2002-01-20 23:19:57 +01:00
<entry><type>bytea</type></entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>1 or 4 bytes plus the actual binary string</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>variable-length binary string</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
</tbody>
</tgroup>
</table>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
A binary string is a sequence of octets (or bytes). Binary
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
strings are distinguished from character strings by two
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
characteristics: First, binary strings specifically allow storing
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
octets of value zero and other <quote>non-printable</quote>
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
octets (usually, octets outside the range 32 to 126).
Character strings disallow zero octets, and also disallow any
other octet values and sequences of octet values that are invalid
according to the database's selected character set encoding.
Make PQescapeBytea and byteaout consistent with each other, and octal escape all octets outside the range 0x20 to 0x7e. This fixes the problem pointed out by Sergey Yatskevich here: http://archives.postgresql.org/pgsql-bugs/2003-11/msg00140.php
2003-11-30 21:55:09 +01:00
Second, operations on binary strings process the actual bytes,
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
whereas the processing of character strings depends on locale settings.
In short, binary strings are appropriate for storing data that the
programmer thinks of as <quote>raw bytes</>, whereas character
strings are appropriate for storing text.
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</para>
Markup additions and spell check. (covers User's Guide)
2001-09-09 19:21:59 +02:00
<para>
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
When entering <type>bytea</type> values, octets of certain
values <emphasis>must</emphasis> be escaped (but all octet
values <emphasis>can</emphasis> be escaped) when used as part
of a string literal in an <acronym>SQL</acronym> statement. In
general, to escape an octet, it is converted into the three-digit
octal number equivalent of its decimal octet value, and preceded
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
by two backslashes. <xref linkend="datatype-binary-sqlesc">
shows the characters that must be escaped, and gives the alternate
escape sequences where applicable.
Markup additions and spell check. (covers User's Guide)
2001-09-09 19:21:59 +02:00
</para>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<table id="datatype-binary-sqlesc">
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title><type>bytea</> Literal Escaped Octets</title>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<tgroup cols="5">
<thead>
<row>
Peter Eisentraut wrote: > So I would base this discussion on the premise "bytea stores binary data" > (insert examples). > > Some stylistic issues: > > bytea => <type>bytea</type> > > NULLs => zero bytes/bytes of value zero ("NULL" is too overloaded) > > 'non-printable' => <quote>nonprintable</quote> > > MUST => <emphasis>must</emphasis> > Here's a patch against *CVS tip* to address Peter's comments. Please let me know what you think! Joe Conway
2001-11-21 04:17:22 +01:00
<entry>Decimal Octet Value</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<entry>Description</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Escaped Input Representation</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<entry>Example</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Output Representation</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
</thead>
<tbody>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>0</entry>
<entry>zero octet</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>E'\\000'</literal></entry>
<entry><literal>SELECT E'\\000'::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>\000</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>39</entry>
<entry>single quote</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>''''</literal> or <literal>E'\\047'</literal></entry>
<entry><literal>SELECT E'\''::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>'</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>92</entry>
<entry>backslash</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>E'\\\\'</literal> or <literal>E'\\134'</literal></entry>
<entry><literal>SELECT E'\\\\'::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>\\</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
Make PQescapeBytea and byteaout consistent with each other, and octal escape all octets outside the range 0x20 to 0x7e. This fixes the problem pointed out by Sergey Yatskevich here: http://archives.postgresql.org/pgsql-bugs/2003-11/msg00140.php
2003-11-30 21:55:09 +01:00
<row>
<entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>E'\\<replaceable>xxx'</></literal> (octal value)</entry>
<entry><literal>SELECT E'\\001'::bytea;</literal></entry>
Make PQescapeBytea and byteaout consistent with each other, and octal escape all octets outside the range 0x20 to 0x7e. This fixes the problem pointed out by Sergey Yatskevich here: http://archives.postgresql.org/pgsql-bugs/2003-11/msg00140.php
2003-11-30 21:55:09 +01:00
<entry><literal>\001</literal></entry>
</row>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</tbody>
</tgroup>
</table>
<para>
Make PQescapeBytea and byteaout consistent with each other, and octal escape all octets outside the range 0x20 to 0x7e. This fixes the problem pointed out by Sergey Yatskevich here: http://archives.postgresql.org/pgsql-bugs/2003-11/msg00140.php
2003-11-30 21:55:09 +01:00
The requirement to escape <quote>non-printable</quote> octets actually
varies depending on locale settings. In some instances you can get away
with leaving them unescaped. Note that the result in each of the examples
in <xref linkend="datatype-binary-sqlesc"> was exactly one octet in
length, even though the output representation of the zero octet and
backslash are more than one character.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
</para>
<para>
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
The reason that you have to write so many backslashes, as shown
in <xref linkend="datatype-binary-sqlesc">, is that an input
string written as a string literal must pass through two parse
phases in the <productname>PostgreSQL</productname> server.
The first backslash of each pair is interpreted as an escape
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
character by the string-literal parser (assuming escape string
syntax is used) and is therefore consumed, leaving the second backslash of the
pair. (Dollar-quoted strings can be used to avoid this level
of escaping.) The remaining backslash is then recognized by the
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
<type>bytea</type> input function as starting either a three
digit octal value or escaping another backslash. For example,
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
a string literal passed to the server as <literal>E'\\001'</literal>
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
becomes <literal>\001</literal> after passing through the
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
escape string parser. The <literal>\001</literal> is then sent
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
to the <type>bytea</type> input function, where it is converted
to a single octet with a decimal value of 1. Note that the
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
single-quote character is not treated specially by <type>bytea</type>,
Add "(assuming <varname>standard_conforming_strings</> is <literal>off</>)" clauses for bytea.
2006-11-23 05:27:33 +01:00
so it follows the normal rules for string literals. (See also
<xref linkend="sql-syntax-strings">.)
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
</para>
<para>
<type>Bytea</type> octets are also escaped in the output. In general, each
<quote>non-printable</quote> octet is converted into
its equivalent three-digit octal value and preceded by one backslash.
Peter Eisentraut wrote: > So I would base this discussion on the premise "bytea stores binary data" > (insert examples). > > Some stylistic issues: > > bytea => <type>bytea</type> > > NULLs => zero bytes/bytes of value zero ("NULL" is too overloaded) > > 'non-printable' => <quote>nonprintable</quote> > > MUST => <emphasis>must</emphasis> > Here's a patch against *CVS tip* to address Peter's comments. Please let me know what you think! Joe Conway
2001-11-21 04:17:22 +01:00
Most <quote>printable</quote> octets are represented by their standard
representation in the client character set. The octet with decimal
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
value 92 (backslash) has a special alternative output representation.
Peter Eisentraut wrote: > So I would base this discussion on the premise "bytea stores binary data" > (insert examples). > > Some stylistic issues: > > bytea => <type>bytea</type> > > NULLs => zero bytes/bytes of value zero ("NULL" is too overloaded) > > 'non-printable' => <quote>nonprintable</quote> > > MUST => <emphasis>must</emphasis> > Here's a patch against *CVS tip* to address Peter's comments. Please let me know what you think! Joe Conway
2001-11-21 04:17:22 +01:00
Details are in <xref linkend="datatype-binary-resesc">.
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</para>
<table id="datatype-binary-resesc">
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title><type>bytea</> Output Escaped Octets</title>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<tgroup cols="5">
<thead>
<row>
Peter Eisentraut wrote: > So I would base this discussion on the premise "bytea stores binary data" > (insert examples). > > Some stylistic issues: > > bytea => <type>bytea</type> > > NULLs => zero bytes/bytes of value zero ("NULL" is too overloaded) > > 'non-printable' => <quote>nonprintable</quote> > > MUST => <emphasis>must</emphasis> > Here's a patch against *CVS tip* to address Peter's comments. Please let me know what you think! Joe Conway
2001-11-21 04:17:22 +01:00
<entry>Decimal Octet Value</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<entry>Description</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Escaped Output Representation</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
<entry>Example</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Output Result</entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
</thead>
<tbody>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>92</entry>
<entry>backslash</entry>
<entry><literal>\\</literal></entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>SELECT E'\\134'::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>\\</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><literal>\<replaceable>xxx</></literal> (octal value)</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>SELECT E'\\001'::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>\001</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
<row>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry>32 to 126</entry>
<entry><quote>printable</quote> octets</entry>
Make PQescapeBytea and byteaout consistent with each other, and octal escape all octets outside the range 0x20 to 0x7e. This fixes the problem pointed out by Sergey Yatskevich here: http://archives.postgresql.org/pgsql-bugs/2003-11/msg00140.php
2003-11-30 21:55:09 +01:00
<entry>client character set representation</entry>
Update documentation for backslashes to mention escape string syntax more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
2007-01-30 23:29:23 +01:00
<entry><literal>SELECT E'\\176'::bytea;</literal></entry>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<entry><literal>~</literal></entry>
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</row>
</tbody>
</tgroup>
</table>
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
Depending on the front end to <productname>PostgreSQL</> you use,
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
you might have additional work to do in terms of escaping and
unescaping <type>bytea</type> strings. For example, you might also
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
have to escape line feeds and carriage returns if your interface
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
automatically translates these.
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
</para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
<para>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
The <acronym>SQL</acronym> standard defines a different binary
string type, called <type>BLOB</type> or <type>BINARY LARGE
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
OBJECT</type>. The input format is different from
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<type>bytea</type>, but the provided functions and operators are
mostly the same.
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</sect1>
Markup additions and spell check. (covers User's Guide)
2001-09-09 19:21:59 +02:00
I've created a new section to func.sgml, "Binary String Functions and Operators", plagiarized shamelessly from the "String Functions and Operators" section. There were enough differences that it made sense (at least to me) to give this its own section instead of cramming it in with normal string functions. This way I could also make the examples relevant, which is particularly important for bytea. One thing I think worth mentioning: while documenting the trim() function I realized that I never implemented the bytea equivalent of rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim, available with text, are not available with bytea (I'd be happy to correct this, but since it would require an initdb, I guess not until 7.3) -- the submitted doc accurately reflects this. I will look for other areas of the docs that need mention of bytea, but any guidance would be much appreciated. -- Here's a second bytea documentation patch. This one significantly expands the "Binary Data" section added by Bruce recently. Joe Conway
2001-11-20 16:42:44 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-datetime">
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
<title>Date/Time Types</title>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm zone="datatype-datetime">
<primary>date</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>time</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>time without time zone</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>time with time zone</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>timestamp</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>timestamp with time zone</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>timestamp without time zone</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>interval</primary>
</indexterm>
<indexterm zone="datatype-datetime">
<primary>time span</primary>
</indexterm>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
<para>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> supports the full set of
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<acronym>SQL</acronym> date and time types, shown in <xref
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
linkend="datatype-datetime-table">. The operations available
on these data types are described in
<xref linkend="functions-datetime">.
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</para>
Include new cidr and inet data types.
1998-10-27 07:14:41 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Date/Time Types</title>
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
<tgroup cols="6">
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
<thead>
<row>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>Description</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Low Value</entry>
<entry>High Value</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>Resolution</entry>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</row>
</thead>
<tbody>
<row>
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
<entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>8 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>both date and time</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>4713 BC</entry>
Minor wordsmithing in datetime docs to try to address gripes raised by cnliou.
2003-12-01 21:34:53 +01:00
<entry>5874897 AD</entry>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<entry>1 microsecond / 14 digits</entry>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</row>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<row>
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
<entry><type>timestamp [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<entry>8 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>both date and time, with time zone</entry>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
<entry>4713 BC</entry>
Minor wordsmithing in datetime docs to try to address gripes raised by cnliou.
2003-12-01 21:34:53 +01:00
<entry>5874897 AD</entry>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<entry>1 microsecond / 14 digits</entry>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
</row>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
<row>
Type interval takes a precision, too.
2001-12-23 21:21:37 +01:00
<entry><type>interval [ (<replaceable>p</replaceable>) ]</type></entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>12 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>time intervals</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>-178000000 years</entry>
<entry>178000000 years</entry>
Clarify that the --enable-integer-datetimes switch affects the time and interval datatypes as well as timestamp.
2005-01-17 19:47:15 +01:00
<entry>1 microsecond / 14 digits</entry>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</row>
<row>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry><type>date</type></entry>
<entry>4 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>dates only</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>4713 BC</entry>
Reject out-of-range dates in date_in(). Kris Jurka
2006-02-09 04:39:17 +01:00
<entry>5874897 AD</entry>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<entry>1 day</entry>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</row>
<row>
Document the precision arguments for date/time types per SQL9x. Update the list of recognized time zones. Document the range of arguments allowed for SET TIME ZONE. Still need to add info on other date/time symbols (e.g. "AM", "T") and to freshen the docs on the date/time parsing rules.
2001-12-29 19:35:54 +01:00
<entry><type>time [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
Since 7.1 the data type size of TIME has been increased.
2001-08-31 03:55:25 +02:00
<entry>8 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>times of day only</entry>
Fix documentation to specify the correct range of timezone offsets for type time with time zone, ie, +/- 13:59 not +/- 12:00. Also some minor wording improvements.
2005-10-22 21:33:57 +02:00
<entry>00:00:00</entry>
Allow times of 24:00:00 to match rounding behavior: regression=# select '23:59:59.9'::time(0); time ---------- 24:00:00 (1 row) This is bad because: regression=# select '24:00:00'::time(0); ERROR: date/time field value out of range: "24:00:00" The last example now works.
2005-10-14 13:47:57 +02:00
<entry>24:00:00</entry>
Clarify that the --enable-integer-datetimes switch affects the time and interval datatypes as well as timestamp.
2005-01-17 19:47:15 +01:00
<entry>1 microsecond / 14 digits</entry>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</row>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<row>
Document the precision arguments for date/time types per SQL9x. Update the list of recognized time zones. Document the range of arguments allowed for SET TIME ZONE. Still need to add info on other date/time symbols (e.g. "AM", "T") and to freshen the docs on the date/time parsing rules.
2001-12-29 19:35:54 +01:00
<entry><type>time [ (<replaceable>p</replaceable>) ] with time zone</type></entry>
Since 7.1 the data type size of TIME has been increased.
2001-08-31 03:55:25 +02:00
<entry>12 bytes</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>times of day only, with time zone</entry>
Fix up timetz input so that a date is required only when the specified timezone actually has a daylight-savings rule. This avoids breaking cases that used to work because they went through the DecodePosixTimezone code path. Per contrib regression failures (mea culpa for not running those yesterday...). Also document the already-applied change to allow GMT offsets up to 14 hours.
2006-10-18 18:43:14 +02:00
<entry>00:00:00+1459</entry>
<entry>24:00:00-1459</entry>
Clarify that the --enable-integer-datetimes switch affects the time and interval datatypes as well as timestamp.
2005-01-17 19:47:15 +01:00
<entry>1 microsecond / 14 digits</entry>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
</row>
Include specific info on available timezones. Document date/time input parsing procedure.
1999-05-04 04:22:13 +02:00
</tbody>
</tgroup>
</table>
Minor wordsmithing in datetime docs to try to address gripes raised by cnliou.
2003-12-01 21:34:53 +01:00
<note>
<para>
Prior to <productname>PostgreSQL</productname> 7.3, writing just
<type>timestamp</type> was equivalent to <type>timestamp with
time zone</type>. This was changed for SQL compliance.
</para>
</note>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<type>time</type>, <type>timestamp</type>, and
<type>interval</type> accept an optional precision value
<replaceable>p</replaceable> which specifies the number of
fractional digits retained in the seconds field. By default, there
is no explicit bound on precision. The allowed range of
<replaceable>p</replaceable> is from 0 to 6 for the
Repair array subscript overrun identified by Yichen Xie. Reduce the value of MAX_TIME_PRECISION in floating-point-timestamp-storage case from 13 to 10, which is as much as time_out is actually willing to print. (The alternative of increasing the number of digits we are willing to print looks risky; we might find ourselves printing roundoff garbage.)
2003-01-29 02:08:42 +01:00
<type>timestamp</type> and <type>interval</type> types.
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
</para>
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
<note>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
When <type>timestamp</> values are stored as double precision floating-point
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
numbers (currently the default), the effective limit of precision
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
might be less than 6. <type>timestamp</type> values are stored as seconds
Minor wordsmithing in datetime docs to try to address gripes raised by cnliou.
2003-12-01 21:34:53 +01:00
before or after midnight 2000-01-01. Microsecond precision is achieved for
dates within a few years of 2000-01-01, but the precision degrades for
dates further away. When <type>timestamp</type> values are stored as
eight-byte integers (a compile-time
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
option), microsecond precision is available over the full range of
Minor wordsmithing in datetime docs to try to address gripes raised by cnliou.
2003-12-01 21:34:53 +01:00
values. However eight-byte integer timestamps have a more limited range of
Clarify that the --enable-integer-datetimes switch affects the time and interval datatypes as well as timestamp.
2005-01-17 19:47:15 +01:00
dates than shown above: from 4713 BC up to 294276 AD. The same
compile-time option also determines whether <type>time</type> and
<type>interval</type> values are stored as floating-point or eight-byte
integers. In the floating-point case, large <type>interval</type> values
degrade in precision as the size of the interval increases.
Update description of timestamp types for 7.3 implementation.
2002-10-31 23:18:42 +01:00
</para>
</note>
Repair array subscript overrun identified by Yichen Xie. Reduce the value of MAX_TIME_PRECISION in floating-point-timestamp-storage case from 13 to 10, which is as much as time_out is actually willing to print. (The alternative of increasing the number of digits we are willing to print looks risky; we might find ourselves printing roundoff garbage.)
2003-01-29 02:08:42 +01:00
<para>
For the <type>time</type> types, the allowed range of
<replaceable>p</replaceable> is from 0 to 6 when eight-byte integer
storage is used, or from 0 to 10 when floating-point storage is used.
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<para>
The type <type>time with time zone</type> is defined by the SQL
standard, but the definition exhibits properties which lead to
questionable usefulness. In most cases, a combination of
<type>date</type>, <type>time</type>, <type>timestamp without time
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
zone</type>, and <type>timestamp with time zone</type> should
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
provide a complete range of date/time functionality required by
any application.
</para>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<para>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
The types <type>abstime</type>
and <type>reltime</type> are lower precision types which are used internally.
Remove the last traces of datatypes datetime and timespan.
2002-05-03 06:11:08 +02:00
You are discouraged from using these types in new
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
applications and are encouraged to move any old
ones over when appropriate. Any or all of these internal types
might disappear in a future release.
</para>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-datetime-input">
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<title>Date/Time Input</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
Date and time input is accepted in almost any reasonable format, including
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
ISO 8601, <acronym>SQL</acronym>-compatible,
traditional <productname>POSTGRES</productname>, and others.
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
For some formats, ordering of month, day, and year in date input is
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
ambiguous and there is support for specifying the expected
Refer to GUC variables using <xref> tags rather than <varname> tags, where appropriate. Add "id" and "xreflabel" tags to the descriptions of the GUC variables to facilitate this. Also make a few minor docs cleanups.
2004-03-09 17:57:47 +01:00
ordering of these fields. Set the <xref linkend="guc-datestyle"> parameter
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
to <literal>MDY</> to select month-day-year interpretation,
<literal>DMY</> to select day-month-year interpretation, or
<literal>YMD</> to select year-month-day interpretation.
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</para>
<para>
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
<productname>PostgreSQL</productname> is more flexible in
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
handling date/time input than the
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
<acronym>SQL</acronym> standard requires.
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
See <xref linkend="datetime-appendix">
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
for the exact parsing rules of date/time input and for the
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
recognized text fields including months, days of the week, and
time zones.
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
</para>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<para>
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
Remember that any date or time literal input needs to be enclosed
in single quotes, like text strings. Refer to
<xref linkend="sql-syntax-constants-generic"> for more
information.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<acronym>SQL</acronym> requires the following syntax
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
<synopsis>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
<replaceable>type</replaceable> [ (<replaceable>p</replaceable>) ] '<replaceable>value</replaceable>'
Add some links from data type chapter to section on literal constants.
2001-01-26 23:04:22 +01:00
</synopsis>
Spiff up discussion of precision on date/time data types. Add a NetBSD/alpha and update info on a few other platforms.
2001-12-21 04:54:02 +01:00
where <replaceable>p</replaceable> in the optional precision
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
specification is an integer corresponding to the number of
fractional digits in the seconds field. Precision can be
specified for <type>time</type>, <type>timestamp</type>, and
<type>interval</type> types. The allowed values are mentioned
above. If no precision is specified in a constant specification,
it defaults to the precision of the literal value.
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<sect3>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title>Dates</title>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>date</primary>
</indexterm>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<xref linkend="datatype-datetime-date-table"> shows some possible
inputs for the <type>date</type> type.
</para>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-date-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Date Input</title>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<tgroup cols="2">
<thead>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>Example</entry>
<entry>Description</entry>
</row>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
</thead>
<tbody>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>January 8, 1999</entry>
<entry>unambiguous in any <varname>datestyle</varname> input mode</entry>
</row>
<row>
<entry>1999-01-08</entry>
Fix datetime input parsing to accept YYYY-MONTHNAME-DD and related syntaxes, which had been unintentionally broken by recent changes to tighten up the DateStyle rules for all-numeric date input. Add documentation and regression tests for this, too.
2003-11-16 21:29:16 +01:00
<entry>ISO 8601; January 8 in any mode
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
(recommended format)</entry>
</row>
<row>
<entry>1/8/1999</entry>
<entry>January 8 in <literal>MDY</> mode;
August 1 in <literal>DMY</> mode</entry>
</row>
<row>
<entry>1/18/1999</entry>
<entry>January 18 in <literal>MDY</> mode;
rejected in other modes</entry>
</row>
<row>
<entry>01/02/03</entry>
<entry>January 2, 2003 in <literal>MDY</> mode;
February 1, 2003 in <literal>DMY</> mode;
February 3, 2001 in <literal>YMD</> mode
</entry>
</row>
Fix datetime input parsing to accept YYYY-MONTHNAME-DD and related syntaxes, which had been unintentionally broken by recent changes to tighten up the DateStyle rules for all-numeric date input. Add documentation and regression tests for this, too.
2003-11-16 21:29:16 +01:00
<row>
<entry>1999-Jan-08</entry>
<entry>January 8 in any mode</entry>
</row>
<row>
<entry>Jan-08-1999</entry>
<entry>January 8 in any mode</entry>
</row>
<row>
<entry>08-Jan-1999</entry>
<entry>January 8 in any mode</entry>
</row>
<row>
<entry>99-Jan-08</entry>
<entry>January 8 in <literal>YMD</> mode, else error</entry>
</row>
<row>
<entry>08-Jan-99</entry>
<entry>January 8, except error in <literal>YMD</> mode</entry>
</row>
<row>
<entry>Jan-08-99</entry>
<entry>January 8, except error in <literal>YMD</> mode</entry>
</row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>19990108</entry>
Random copy-editing.
2003-11-04 10:55:39 +01:00
<entry>ISO 8601; January 8, 1999 in any mode</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
<row>
<entry>990108</entry>
Random copy-editing.
2003-11-04 10:55:39 +01:00
<entry>ISO 8601; January 8, 1999 in any mode</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
<row>
<entry>1999.008</entry>
<entry>year and day of year</entry>
</row>
<row>
<entry>J2451187</entry>
<entry>Julian day</entry>
</row>
<row>
<entry>January 8, 99 BC</entry>
<entry>year 99 before the Common Era</entry>
</row>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
</tbody>
</tgroup>
</table>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</sect3>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<sect3>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title>Times</title>
Update docs for TIME WITHOUT TIME ZONE. Add information on SET SESSION CHARACTERISTICS. Fix references to pg_hba.conf(5) since that is no longer a man page.
2000-07-14 17:26:21 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>time</primary>
</indexterm>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
<indexterm>
<primary>time without time zone</primary>
</indexterm>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<indexterm>
<primary>time with time zone</primary>
</indexterm>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
Update docs for TIME WITHOUT TIME ZONE. Add information on SET SESSION CHARACTERISTICS. Fix references to pg_hba.conf(5) since that is no longer a man page.
2000-07-14 17:26:21 +02:00
<para>
Allow a time zone to be specified (and silently ignored) in the input for type 'time without time zone', as we already did for type 'timestamp without time zone'. This patch was proposed by Tom Lockhart on 7-Nov-02, but he never got around to applying it. Adjust regression tests and documentation to match.
2003-01-31 02:08:08 +01:00
The time-of-day types are <type>time [
(<replaceable>p</replaceable>) ] without time zone</type> and
<type>time [ (<replaceable>p</replaceable>) ] with time
zone</type>. Writing just <type>time</type> is equivalent to
<type>time without time zone</type>.
Update docs for TIME WITHOUT TIME ZONE. Add information on SET SESSION CHARACTERISTICS. Fix references to pg_hba.conf(5) since that is no longer a man page.
2000-07-14 17:26:21 +02:00
</para>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Valid input for these types consists of a time of day followed
by an optional time zone. (See <xref
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
linkend="datatype-datetime-time-table">
and <xref linkend="datatype-timezone-table">.) If a time zone is
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
specified in the input for <type>time without time zone</type>,
Arrange for timezone names to be recognized case-insensitively; for example SET TIME ZONE 'america/new_york' works now. This seems a good idea on general user-friendliness grounds, and is part of the solution to the timestamp-input parsing problems I noted recently.
2006-10-16 21:58:27 +02:00
it is silently ignored. You can also specify a date but it will
Fix up timetz input so that a date is required only when the specified timezone actually has a daylight-savings rule. This avoids breaking cases that used to work because they went through the DecodePosixTimezone code path. Per contrib regression failures (mea culpa for not running those yesterday...). Also document the already-applied change to allow GMT offsets up to 14 hours.
2006-10-18 18:43:14 +02:00
be ignored, except when you use a time zone name that involves a
daylight-savings rule, such as
Please find attached two patches for documentation and regression tests for the usage of full time zone names. Joachim Wieland
2006-07-06 03:46:38 +02:00
<literal>America/New_York</literal>. In this case specifying the date
Arrange for timezone names to be recognized case-insensitively; for example SET TIME ZONE 'america/new_york' works now. This seems a good idea on general user-friendliness grounds, and is part of the solution to the timestamp-input parsing problems I noted recently.
2006-10-16 21:58:27 +02:00
is required in order to determine whether standard or daylight-savings
time applies. The appropriate time zone offset is recorded in the
<type>time with time zone</type> value.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-time-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Time Input</title>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
<tgroup cols="2">
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<thead>
<row>
<entry>Example</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>04:05:06.789</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05:06</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>040506</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05 AM</literal></entry>
<entry>same as 04:05; AM does not affect value</entry>
</row>
<row>
<entry><literal>04:05 PM</literal></entry>
More < and > cleanups converted to ampersands.
2005-01-22 23:56:36 +01:00
<entry>same as 16:05; input hour must be &lt;= 12</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
<row>
<entry><literal>04:05:06.789-8</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05:06-08:00</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05-08:00</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>040506-08</literal></entry>
<entry>ISO 8601</entry>
</row>
<row>
<entry><literal>04:05:06 PST</literal></entry>
Arrange for timezone names to be recognized case-insensitively; for example SET TIME ZONE 'america/new_york' works now. This seems a good idea on general user-friendliness grounds, and is part of the solution to the timestamp-input parsing problems I noted recently.
2006-10-16 21:58:27 +02:00
<entry>time zone specified by abbreviation</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
Please find attached two patches for documentation and regression tests for the usage of full time zone names. Joachim Wieland
2006-07-06 03:46:38 +02:00
<row>
<entry><literal>2003-04-12 04:05:06 America/New_York</literal></entry>
<entry>time zone specified by full name</entry>
</row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</tbody>
</tgroup>
</table>
Write up new TIME WITH TIME ZONE type.
2000-03-14 23:52:53 +01:00
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
<table tocentry="1" id="datatype-timezone-table">
<title>Time Zone Input</title>
<tgroup cols="2">
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<thead>
<row>
<entry>Example</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>PST</literal></entry>
Fix up some problems in handling of zic-style time zone names in datetime input routines. Remove the former "DecodePosixTimezone" function in favor of letting the zic code handle POSIX-style zone specs (see tzparse()). In particular this means that "PST+3" now means the same as "-03", whereas it used to mean "-11" --- the zone abbreviation is effectively just a noise word in this syntax. Make sure that all named and POSIX-style zone names will be parsed as a single token. Fix long-standing bogosities in printing and input of fractional-hour timezone offsets (since the tzparse() code will accept these, we'd better make 'em work). Also correct an error in the original coding of the zic-zone-name patch: in "timestamp without time zone" input, zone names are supposed to be allowed but ignored, but the coding was such that the zone changed the interpretation anyway.
2006-10-17 23:03:21 +02:00
<entry>Abbreviation (for Pacific Standard Time)</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
Please find attached two patches for documentation and regression tests for the usage of full time zone names. Joachim Wieland
2006-07-06 03:46:38 +02:00
<row>
<entry><literal>America/New_York</literal></entry>
<entry>Full time zone name</entry>
</row>
Fix up some problems in handling of zic-style time zone names in datetime input routines. Remove the former "DecodePosixTimezone" function in favor of letting the zic code handle POSIX-style zone specs (see tzparse()). In particular this means that "PST+3" now means the same as "-03", whereas it used to mean "-11" --- the zone abbreviation is effectively just a noise word in this syntax. Make sure that all named and POSIX-style zone names will be parsed as a single token. Fix long-standing bogosities in printing and input of fractional-hour timezone offsets (since the tzparse() code will accept these, we'd better make 'em work). Also correct an error in the original coding of the zic-zone-name patch: in "timestamp without time zone" input, zone names are supposed to be allowed but ignored, but the coding was such that the zone changed the interpretation anyway.
2006-10-17 23:03:21 +02:00
<row>
<entry><literal>PST8PDT</literal></entry>
<entry>POSIX-style time zone specification</entry>
</row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry><literal>-8:00</literal></entry>
<entry>ISO-8601 offset for PST</entry>
</row>
<row>
<entry><literal>-800</literal></entry>
<entry>ISO-8601 offset for PST</entry>
</row>
<row>
<entry><literal>-8</literal></entry>
<entry>ISO-8601 offset for PST</entry>
</row>
<row>
<entry><literal>zulu</literal></entry>
Fix datetime input parsing to accept YYYY-MONTHNAME-DD and related syntaxes, which had been unintentionally broken by recent changes to tighten up the DateStyle rules for all-numeric date input. Add documentation and regression tests for this, too.
2003-11-16 21:29:16 +01:00
<entry>Military abbreviation for UTC</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
<row>
<entry><literal>z</literal></entry>
<entry>Short form of <literal>zulu</literal></entry>
</row>
</tbody>
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
</tgroup>
</table>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<para>
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
Refer to <xref linkend="datatype-timezones"> for more information on how
to specify time zones.
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</sect3>
<sect3>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Time Stamps</title>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<indexterm>
<primary>timestamp</primary>
</indexterm>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
<indexterm>
<primary>timestamp with time zone</primary>
</indexterm>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
<indexterm>
<primary>timestamp without time zone</primary>
</indexterm>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<para>
Valid input for the time stamp types consists of a concatenation
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
of a date and a time, followed by an optional time zone,
followed by an optional <literal>AD</literal> or <literal>BC</literal>.
(Alternatively, <literal>AD</literal>/<literal>BC</literal> can appear
before the time zone, but this is not the preferred ordering.)
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
Thus:
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
Spacing improvements
2001-11-09 00:36:55 +01:00
<programlisting>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
1999-01-08 04:05:06
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</programlisting>
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
and:
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<programlisting>
1999-01-08 04:05:06 -8:00
Spacing improvements
2001-11-09 00:36:55 +01:00
</programlisting>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
are valid values, which follow the <acronym>ISO</acronym> 8601
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
standard. In addition, the wide-spread format:
Spacing improvements
2001-11-09 00:36:55 +01:00
<programlisting>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
January 8 04:05:06 1999 PST
Spacing improvements
2001-11-09 00:36:55 +01:00
</programlisting>
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
is supported.
</para>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
<para>
Update of conformance information to SQL:2003 by Troels Arvin, Simon Riggs, Elein Mustain Make spelling of SQL standard names uniform.
2004-11-27 22:27:08 +01:00
The <acronym>SQL</acronym> standard differentiates <type>timestamp without time zone</type>
Fix documentation to specify the correct range of timezone offsets for type time with time zone, ie, +/- 13:59 not +/- 12:00. Also some minor wording improvements.
2005-10-22 21:33:57 +02:00
and <type>timestamp with time zone</type> literals by the presence of a
<quote>+</quote> or <quote>-</quote>. Hence, according to the standard,
Update of conformance information to SQL:2003 by Troels Arvin, Simon Riggs, Elein Mustain Make spelling of SQL standard names uniform.
2004-11-27 22:27:08 +01:00
<programlisting>TIMESTAMP '2004-10-19 10:23:54'</programlisting>
is a <type>timestamp without time zone</type>, while
<programlisting>TIMESTAMP '2004-10-19 10:23:54+02'</programlisting>
is a <type>timestamp with time zone</type>.
Fix documentation to specify the correct range of timezone offsets for type time with time zone, ie, +/- 13:59 not +/- 12:00. Also some minor wording improvements.
2005-10-22 21:33:57 +02:00
<productname>PostgreSQL</productname> never examines the content of a
literal string before determining its type, and therefore will treat
both of the above as <type>timestamp without time zone</type>. To
ensure that a literal is treated as <type>timestamp with time
zone</type>, give it the correct explicit type:
Update of conformance information to SQL:2003 by Troels Arvin, Simon Riggs, Elein Mustain Make spelling of SQL standard names uniform.
2004-11-27 22:27:08 +01:00
<programlisting>TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'</programlisting>
Fix documentation to specify the correct range of timezone offsets for type time with time zone, ie, +/- 13:59 not +/- 12:00. Also some minor wording improvements.
2005-10-22 21:33:57 +02:00
In a literal that has been decided to be <type>timestamp without time
zone</type>, <productname>PostgreSQL</productname> will silently ignore
any time zone indication.
That is, the resulting value is derived from the date/time
Add information on new timestamp and timestamptz data types. Start chapter on recovery techniques. Still needs work for release.
2001-09-28 10:15:35 +02:00
fields in the input value, and is not adjusted for time zone.
</para>
Update list of currently supported platforms. Mention SQL9x precision syntax for date/time types. Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:23 +01:00
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
<para>
For <type>timestamp with time zone</type>, the internally stored
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
value is always in UTC (Universal
Coordinated Time, traditionally known as Greenwich Mean Time,
<acronym>GMT</>). An input value that has an explicit
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
time zone specified is converted to UTC using the appropriate offset
for that time zone. If no time zone is stated in the input string,
then it is assumed to be in the time zone indicated by the system's
Refer to GUC variables using <xref> tags rather than <varname> tags, where appropriate. Add "id" and "xreflabel" tags to the descriptions of the GUC variables to facilitate this. Also make a few minor docs cleanups.
2004-03-09 17:57:47 +01:00
<xref linkend="guc-timezone"> parameter, and is converted to UTC using the
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
offset for the <varname>timezone</> zone.
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
</para>
<para>
When a <type>timestamp with time
zone</type> value is output, it is always converted from UTC to the
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
current <varname>timezone</> zone, and displayed as local time in that
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
zone. To see the time in another time zone, either change
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<varname>timezone</> or use the <literal>AT TIME ZONE</> construct
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
(see <xref linkend="functions-datetime-zoneconvert">).
</para>
<para>
Conversions between <type>timestamp without time zone</type> and
<type>timestamp with time zone</type> normally assume that the
<type>timestamp without time zone</type> value should be taken or given
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
as <varname>timezone</> local time. A different zone reference can
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
be specified for the conversion using <literal>AT TIME ZONE</>.
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</sect3>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<sect3>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title>Intervals</title>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>interval</primary>
</indexterm>
Add tables of allowed values and formats for date/time input types. Include info for time zones, days of week, months. Procedural description of date input parsing is not yet complete.
1999-01-19 17:08:26 +01:00
<para>
A bunch of small doco updates motivated by scanning the comments on the interactive docs.
2001-11-19 04:58:25 +01:00
<type>interval</type> values can be written with the following syntax:
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Spacing improvements
2001-11-09 00:36:55 +01:00
<programlisting>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<optional>@</> <replaceable>quantity</> <replaceable>unit</> <optional><replaceable>quantity</> <replaceable>unit</>...</> <optional><replaceable>direction</></optional>
Spacing improvements
2001-11-09 00:36:55 +01:00
</programlisting>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Where: <replaceable>quantity</> is a number (possibly signed);
Fix a bug in input processing for the "interval" type. Previously, "microsecond" and "millisecond" units were not considered valid input by themselves, which caused inputs like "1 millisecond" to be rejected erroneously. Update the docs, add regression tests, and backport to 8.2 and 8.1
2007-05-29 06:58:43 +02:00
<replaceable>unit</> is <literal>microsecond</literal>,
<literal>millisecond</literal>, <literal>second</literal>,
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<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>millennium</literal>,
or abbreviations or plurals of these units;
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<replaceable>direction</> can be <literal>ago</literal> or
A bunch of small doco updates motivated by scanning the comments on the interactive docs.
2001-11-19 04:58:25 +01:00
empty. The at sign (<literal>@</>) is optional noise. The amounts
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
of different units are implicitly added up with appropriate
A bunch of small doco updates motivated by scanning the comments on the interactive docs.
2001-11-19 04:58:25 +01:00
sign accounting.
</para>
<para>
Quantities of days, hours, minutes, and seconds can be specified without
Grammatical and spelling fixes.
2001-11-19 10:05:02 +01:00
explicit unit markings. For example, <literal>'1 12:59:10'</> is read
A bunch of small doco updates motivated by scanning the comments on the interactive docs.
2001-11-19 04:58:25 +01:00
the same as <literal>'1 day 12 hours 59 min 10 sec'</>.
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</para>
Type interval takes a precision, too.
2001-12-23 21:21:37 +01:00
<para>
Update interval documenation to mention the storage system used.
2005-12-22 22:45:19 +01:00
The optional subsecond precision <replaceable>p</replaceable> should
be between 0 and 6, and defaults to the precision of the input literal.
</para>
<para>
Internally <type>interval</> values are stored as months, days,
and seconds. This is done because the number of days in a month
varies, and a day can have 23 or 25 hours if a daylight savings
time adjustment is involved. Because intervals are usually created
from constant strings or <type>timestamp</> subtraction, this
storage method works well in most cases. Functions
<function>justify_days</> and <function>justify_hours</> are
available for adjusting days and hours that overflow their normal
periods.
Type interval takes a precision, too.
2001-12-23 21:21:37 +01:00
</para>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</sect3>
Describe the date/time parsing rules. Include specific information on the supported time zones. It's a really big table, so maybe it should go into an appendix instead.
1999-02-13 04:42:10 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<sect3>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Special Values</title>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>time</primary>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<secondary>constants</secondary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
<indexterm>
<primary>date</primary>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<secondary>constants</secondary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<productname>PostgreSQL</productname> supports several
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
special date/time input values for convenience, as shown in <xref
linkend="datatype-datetime-special-table">. The values
<literal>infinity</literal> and <literal>-infinity</literal>
are specially represented inside the system and will be displayed
the same way; but the others are simply notational shorthands
that will be converted to ordinary date/time values when read.
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
(In particular, <literal>now</> and related strings are converted
to a specific time value as soon as they are read.)
All of these values need to be written in single quotes when used
as constants in SQL commands.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-special-table">
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
<title>Special Date/Time Inputs</title>
Fix erroneous column counts in some documentation tables. Brian Gough
2007-04-17 19:30:35 +02:00
<tgroup cols="3">
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<thead>
<row>
<entry>Input String</entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry>Valid Types</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>epoch</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>date</type>, <type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>
</row>
<row>
<entry><literal>infinity</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>later than all other time stamps</entry>
</row>
<row>
<entry><literal>-infinity</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>earlier than all other time stamps</entry>
</row>
<row>
<entry><literal>now</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>date</type>, <type>time</type>, <type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>current transaction's start time</entry>
</row>
<row>
<entry><literal>today</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>date</type>, <type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>midnight today</entry>
</row>
<row>
<entry><literal>tomorrow</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>date</type>, <type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>midnight tomorrow</entry>
</row>
<row>
<entry><literal>yesterday</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>date</type>, <type>timestamp</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>midnight yesterday</entry>
</row>
<row>
<entry><literal>allballs</literal></entry>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<entry><type>time</type></entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>00:00:00.00 UTC</entry>
</row>
</tbody>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
</tgroup>
</table>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<para>
The following <acronym>SQL</acronym>-compatible functions can also
be used to obtain the current time value for the corresponding data
type:
<literal>CURRENT_DATE</literal>, <literal>CURRENT_TIME</literal>,
<literal>CURRENT_TIMESTAMP</literal>, <literal>LOCALTIME</literal>,
<literal>LOCALTIMESTAMP</literal>. The latter four accept an
Update interval documenation to mention the storage system used.
2005-12-22 22:45:19 +01:00
optional subsecond precision specification. (See <xref
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
linkend="functions-datetime-current">.) Note however that these are
SQL functions and are <emphasis>not</> recognized as data input strings.
</para>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
</sect3>
</sect2>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-datetime-output">
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<title>Date/Time Output</title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>date</primary>
<secondary>output format</secondary>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<seealso>formatting</seealso>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
<indexterm>
<primary>time</primary>
<secondary>output format</secondary>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<seealso>formatting</seealso>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
The output format of the date/time types can be set to one of the four
styles ISO 8601,
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<acronym>SQL</acronym> (Ingres), traditional POSTGRES, and
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
German, using the command <literal>SET datestyle</literal>. The default
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
is the <acronym>ISO</acronym> format. (The
<acronym>SQL</acronym> standard requires the use of the ISO 8601
format. The name of the <quote>SQL</quote> output format is a
historical accident.) <xref
linkend="datatype-datetime-output-table"> shows examples of each
output style. The output of the <type>date</type> and
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<type>time</type> types is of course only the date or time part
in accordance with the given examples.
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-output-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Date/Time Output Styles</title>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<tgroup cols="3">
<thead>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>Style Specification</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</thead>
<tbody>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>ISO</entry>
<entry>ISO 8601/SQL standard</entry>
<entry>1997-12-17 07:37:16-08</entry>
</row>
<row>
<entry>SQL</entry>
<entry>traditional style</entry>
<entry>12/17/1997 07:37:16.00 PST</entry>
</row>
<row>
<entry>POSTGRES</entry>
<entry>original style</entry>
<entry>Wed Dec 17 07:37:16 1997 PST</entry>
</row>
<row>
<entry>German</entry>
<entry>regional style</entry>
<entry>17.12.1997 07:37:16.00 PST</entry>
</row>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</tbody>
</tgroup>
</table>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
In the <acronym>SQL</acronym> and POSTGRES styles, day appears before
month if DMY field ordering has been specified, otherwise month appears
before day.
(See <xref linkend="datatype-datetime-input">
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
for how this setting also affects interpretation of input values.)
<xref linkend="datatype-datetime-output2-table"> shows an
example.
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</para>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-datetime-output2-table">
<title>Date Order Conventions</title>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<tgroup cols="3">
<thead>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry><varname>datestyle</varname> Setting</entry>
<entry>Input Ordering</entry>
<entry>Example Output</entry>
</row>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</thead>
<tbody>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry><literal>SQL, DMY</></entry>
<entry><replaceable>day</replaceable>/<replaceable>month</replaceable>/<replaceable>year</replaceable></entry>
<entry>17/12/1997 15:37:16.00 CET</entry>
</row>
<row>
<entry><literal>SQL, MDY</></entry>
<entry><replaceable>month</replaceable>/<replaceable>day</replaceable>/<replaceable>year</replaceable></entry>
<entry>12/17/1997 07:37:16.00 PST</entry>
</row>
<row>
<entry><literal>Postgres, DMY</></entry>
<entry><replaceable>day</replaceable>/<replaceable>month</replaceable>/<replaceable>year</replaceable></entry>
<entry>Wed 17 Dec 07:37:16 1997 PST</entry>
</row>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</tbody>
</tgroup>
</table>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<type>interval</type> output looks like the input format, except
that units like <literal>century</literal> or
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<literal>week</literal> are converted to years and days and
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<literal>ago</literal> is converted to an appropriate sign. In
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
ISO mode the output looks like:
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<programlisting>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<optional> <replaceable>quantity</> <replaceable>unit</> <optional> ... </> </> <optional> <replaceable>days</> </> <optional> <replaceable>hours</>:<replaceable>minutes</>:<replaceable>seconds</> </optional>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</programlisting>
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 :()
1999-08-06 15:43:42 +02:00
</para>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
The date/time styles can be selected by the user using the
Refer to GUC variables using <xref> tags rather than <varname> tags, where appropriate. Add "id" and "xreflabel" tags to the descriptions of the GUC variables to facilitate this. Also make a few minor docs cleanups.
2004-03-09 17:57:47 +01:00
<command>SET datestyle</command> command, the <xref
linkend="guc-datestyle"> parameter in the
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
<filename>postgresql.conf</filename> configuration file, or the
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<envar>PGDATESTYLE</envar> environment variable on the server or
client. The formatting function <function>to_char</function>
(see <xref linkend="functions-formatting">) is also available as
a more flexible way to format the date/time output.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-timezones">
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<title>Time Zones</title>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-timezones">
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>time zone</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<para>
Time zones, and time-zone conventions, are influenced by
political decisions, not just earth geometry. Time zones around the
world became somewhat standardized during the 1900's,
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
but continue to be prone to arbitrary changes, particularly with
respect to daylight-savings rules.
<productname>PostgreSQL</productname> currently supports daylight-savings
rules over the time period 1902 through 2038 (corresponding to the full
range of conventional Unix system time). Times outside that range are
taken to be in <quote>standard time</> for the selected time zone, no
matter what part of the year they fall in.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> endeavors to be compatible with
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
the <acronym>SQL</acronym> standard definitions for typical usage.
However, the <acronym>SQL</acronym> standard has an odd mix of date and
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
time types and capabilities. Two obvious problems are:
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<itemizedlist>
<listitem>
<para>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
Although the <type>date</type> type
does not have an associated time zone, the
<type>time</type> type can.
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
Time zones in the real world have little meaning unless
associated with a date as well as a time,
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
since the offset can vary through the year with daylight-saving
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
time boundaries.
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</para>
</listitem>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<listitem>
<para>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
The default time zone is specified as a constant numeric offset
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
from <acronym>UTC</>. It is therefore not possible to adapt to
daylight-saving time when doing date/time arithmetic across
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<acronym>DST</acronym> boundaries.
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</para>
</listitem>
Add mention of the SERIAL data type. 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.
1998-10-14 18:26:31 +02:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</itemizedlist>
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 :()
1999-08-06 15:43:42 +02:00
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
To address these difficulties, we recommend using date/time types
that contain both date and time when using time zones. We
recommend <emphasis>not</emphasis> using the type <type>time with
time zone</type> (though it is supported by
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> for legacy applications and
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
for compliance with the <acronym>SQL</acronym> standard).
<productname>PostgreSQL</productname> assumes
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
your local time zone for any type containing only date or time.
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 :()
1999-08-06 15:43:42 +02:00
</para>
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
All timezone-aware dates and times are stored internally in
<acronym>UTC</acronym>. They are converted to local time
in the zone specified by the <xref linkend="guc-timezone"> configuration
parameter before being displayed to the client.
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 :()
1999-08-06 15:43:42 +02:00
</para>
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
<para>
<productname>PostgreSQL</productname> allows you to specify time zones in
three different forms:
<itemizedlist>
<listitem>
<para>
A full time zone name, for example <literal>America/New_York</>.
The recognized time zone names are listed in the
<literal>pg_timezone_names</literal> view (see <xref
linkend="view-pg-timezone-names">).
<productname>PostgreSQL</productname> uses the widely-used
<literal>zic</> time zone data for this purpose, so the same
names are also recognized by much other software.
</para>
</listitem>
<listitem>
<para>
A time zone abbreviation, for example <literal>PST</>. Such a
specification merely defines a particular offset from UTC, in
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
contrast to full time zone names which might imply a set of daylight
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
savings transition-date rules as well. The recognized abbreviations
are listed in the <literal>pg_timezone_abbrevs</> view (see <xref
linkend="view-pg-timezone-abbrevs">). You cannot set the
Switch over to using the src/timezone functions for formatting timestamps displayed in the postmaster log. This avoids Windows-specific problems with localized time zone names that are in the wrong encoding, and generally seems like a good idea to forestall other potential platform-dependent issues. To preserve the existing behavior that all backends will log in the same time zone, create a new GUC variable log_timezone that can only be changed on a system-wide basis, and reference log-related calculations to that zone instead of the TimeZone variable. This fixes the issue reported by Hiroshi Saito that timestamps printed by xlog.c startup could be improperly localized on Windows. We still need a simpler patch for that problem in the back branches, however.
2007-08-04 03:26:54 +02:00
configuration parameters <xref linkend="guc-timezone"> or
<xref linkend="guc-log-timezone"> using a time
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
zone abbreviation, but you can use abbreviations in
date/time input values and with the <literal>AT TIME ZONE</>
operator.
</para>
</listitem>
<listitem>
<para>
In addition to the timezone names and abbreviations,
Fix up some problems in handling of zic-style time zone names in datetime input routines. Remove the former "DecodePosixTimezone" function in favor of letting the zic code handle POSIX-style zone specs (see tzparse()). In particular this means that "PST+3" now means the same as "-03", whereas it used to mean "-11" --- the zone abbreviation is effectively just a noise word in this syntax. Make sure that all named and POSIX-style zone names will be parsed as a single token. Fix long-standing bogosities in printing and input of fractional-hour timezone offsets (since the tzparse() code will accept these, we'd better make 'em work). Also correct an error in the original coding of the zic-zone-name patch: in "timestamp without time zone" input, zone names are supposed to be allowed but ignored, but the coding was such that the zone changed the interpretation anyway.
2006-10-17 23:03:21 +02:00
<productname>PostgreSQL</productname> will accept POSIX-style time zone
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
specifications of the form <replaceable>STD</><replaceable>offset</> or
<replaceable>STD</><replaceable>offset</><replaceable>DST</>, where
<replaceable>STD</> is a zone abbreviation, <replaceable>offset</> is a
numeric offset in hours west from UTC, and <replaceable>DST</> is an
optional daylight-savings zone abbreviation, assumed to stand for one
hour ahead of the given offset. For example, if <literal>EST5EDT</>
were not already a recognized zone name, it would be accepted and would
be functionally equivalent to USA East Coast time. When a
daylight-savings zone name is present, it is assumed to be used
Arrange to install a "posixrules" entry in our timezone database, so that POSIX-style timezone specs that don't exactly match any database entry will be treated as having correct USA DST rules. Also, document that this can be changed if you want to use some other DST rules with a POSIX zone spec. We could consider changing localtime.c's TZDEFRULESTRING, but since that facility can only deal with one DST transition rule, it seems fairly useless now; might as well just plan to override it using a "posixrules" entry. Backpatch as far as 8.0. There isn't much we can do in 7.x ... either your libc gets it right, or it doesn't.
2007-03-14 18:38:06 +01:00
according to the same daylight-savings transition rules used in the
<literal>zic</> time zone database's <filename>posixrules</> entry.
In a standard <productname>PostgreSQL</productname> installation,
<filename>posixrules</> is the same as <literal>US/Eastern</>, so
that POSIX-style time zone specifications follow USA daylight-savings
rules. If needed, you can adjust this behavior by replacing the
<filename>posixrules</> file.
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
</para>
</listitem>
</itemizedlist>
There is a conceptual and practical difference between the abbreviations
and the full names: abbreviations always represent a fixed offset from
UTC, whereas most of the full names imply a local daylight-savings time
Fix up timetz input so that a date is required only when the specified timezone actually has a daylight-savings rule. This avoids breaking cases that used to work because they went through the DecodePosixTimezone code path. Per contrib regression failures (mea culpa for not running those yesterday...). Also document the already-applied change to allow GMT offsets up to 14 hours.
2006-10-18 18:43:14 +02:00
rule and so have two possible UTC offsets.
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
</para>
Arrange to install a "posixrules" entry in our timezone database, so that POSIX-style timezone specs that don't exactly match any database entry will be treated as having correct USA DST rules. Also, document that this can be changed if you want to use some other DST rules with a POSIX zone spec. We could consider changing localtime.c's TZDEFRULESTRING, but since that facility can only deal with one DST transition rule, it seems fairly useless now; might as well just plan to override it using a "posixrules" entry. Backpatch as far as 8.0. There isn't much we can do in 7.x ... either your libc gets it right, or it doesn't.
2007-03-14 18:38:06 +01:00
<para>
One should be wary that the POSIX-style time zone feature can
lead to silently accepting bogus input, since there is no check on the
reasonableness of the zone abbreviations. For example, <literal>SET
TIMEZONE TO FOOBAR0</> will work, leaving the system effectively using
a rather peculiar abbreviation for UTC.
Add an explicit comment about POSIX time zone names having the reverse sign convention from everyplace else in Postgres. I don't suppose that this will stop people from being confused, but at least we can say that it's documented.
2007-05-08 19:02:59 +02:00
Another issue to keep in mind is that in POSIX time zone names,
positive offsets are used for locations <emphasis>west</> of Greenwich.
Everywhere else, <productname>PostgreSQL</productname> follows the
ISO-8601 convention that positive timezone offsets are <emphasis>east</>
of Greenwich.
Arrange to install a "posixrules" entry in our timezone database, so that POSIX-style timezone specs that don't exactly match any database entry will be treated as having correct USA DST rules. Also, document that this can be changed if you want to use some other DST rules with a POSIX zone spec. We could consider changing localtime.c's TZDEFRULESTRING, but since that facility can only deal with one DST transition rule, it seems fairly useless now; might as well just plan to override it using a "posixrules" entry. Backpatch as far as 8.0. There isn't much we can do in 7.x ... either your libc gets it right, or it doesn't.
2007-03-14 18:38:06 +01:00
</para>
Arrange for timezone names to be recognized case-insensitively; for example SET TIME ZONE 'america/new_york' works now. This seems a good idea on general user-friendliness grounds, and is part of the solution to the timestamp-input parsing problems I noted recently.
2006-10-16 21:58:27 +02:00
<para>
In all cases, timezone names are recognized case-insensitively.
(This is a change from <productname>PostgreSQL</productname> versions
prior to 8.2, which were case-sensitive in some contexts and not others.)
</para>
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
<para>
Neither full names nor abbreviations are hard-wired into the server;
they are obtained from configuration files stored under
<filename>.../share/timezone/</> and <filename>.../share/timezonesets/</>
of the installation directory
(see <xref linkend="datetime-config-files">).
</para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
The <xref linkend="guc-timezone"> configuration parameter can
be set in the file <filename>postgresql.conf</>, or in any of the
other standard ways described in <xref linkend="runtime-config">.
There are also several special ways to set it:
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 :()
1999-08-06 15:43:42 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<itemizedlist>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<listitem>
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
If <varname>timezone</> is not specified in
Merge postmaster and postgres command into just postgres. postmaster symlink is kept for now for compatibility. To call single-user mode, use postgres --single.
2006-06-18 17:38:37 +02:00
<filename>postgresql.conf</> nor as a server command-line option,
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
the server attempts to use the value of the <envar>TZ</envar>
environment variable as the default time zone. If <envar>TZ</envar>
is not defined or is not any of the time zone names known to
<productname>PostgreSQL</productname>, the server attempts to
determine the operating system's default time zone by checking the
behavior of the C library function <literal>localtime()</>. The
default time zone is selected as the closest match among
<productname>PostgreSQL</productname>'s known time zones.
Switch over to using the src/timezone functions for formatting timestamps displayed in the postmaster log. This avoids Windows-specific problems with localized time zone names that are in the wrong encoding, and generally seems like a good idea to forestall other potential platform-dependent issues. To preserve the existing behavior that all backends will log in the same time zone, create a new GUC variable log_timezone that can only be changed on a system-wide basis, and reference log-related calculations to that zone instead of the TimeZone variable. This fixes the issue reported by Hiroshi Saito that timestamps printed by xlog.c startup could be improperly localized on Windows. We still need a simpler patch for that problem in the back branches, however.
2007-08-04 03:26:54 +02:00
(These rules are also used to choose the default value of
<xref linkend="guc-log-timezone">, if it is not specified.)
Fix breakage in new-in-7.3 timetz_zone() function: was giving random results due to doing arithmetic on uninitialized values. Add some documentation about the AT TIME ZONE construct. Update some other date/time documentation that seemed out of date for 7.3.
2002-11-22 00:31:20 +01:00
</para>
</listitem>
<listitem>
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
The <acronym>SQL</acronym> command <command>SET TIME ZONE</command>
sets the time zone for the session. This is an alternative spelling
of <command>SET TIMEZONE TO</> with a more SQL-spec-compatible syntax.
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</para>
</listitem>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<listitem>
<para>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
The <envar>PGTZ</envar> environment variable, if set at the
client, is used by <application>libpq</application>
applications to send a <command>SET TIME ZONE</command>
command to the server upon connection.
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
</para>
</listitem>
</itemizedlist>
</para>
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 :()
1999-08-06 15:43:42 +02:00
</sect2>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-datetime-internals">
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
<title>Internals</title>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> uses Julian dates
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
for all date/time calculations. They have the nice property of correctly
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
predicting/calculating any date more recent than 4713 BC
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
to far into the future, using the assumption that the length of the
year is 365.2425 days.
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 :()
1999-08-06 15:43:42 +02:00
</para>
<para>
updated install file updated date/time types doc fixed small psql bug removed libpq code that lower-cased db names make notice when long identifier is truncated
2000-01-23 02:27:39 +01:00
Date conventions before the 19th century make for interesting reading,
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
but are not consistent enough to warrant coding into a date/time handler.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
</sect1>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-boolean">
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 :()
1999-08-06 15:43:42 +02:00
<title>Boolean Type</title>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-boolean">
<primary>Boolean</primary>
<secondary>data type</secondary>
</indexterm>
<indexterm zone="datatype-boolean">
<primary>true</primary>
</indexterm>
<indexterm zone="datatype-boolean">
<primary>false</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> provides the
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
standard <acronym>SQL</acronym> type <type>boolean</type>.
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<type>boolean</type> can have one of only two states:
<quote>true</quote> or <quote>false</quote>. A third state,
<quote>unknown</quote>, is represented by the
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<acronym>SQL</acronym> null value.
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
Valid literal values for the <quote>true</quote> state are:
<simplelist>
<member><literal>TRUE</literal></member>
<member><literal>'t'</literal></member>
<member><literal>'true'</literal></member>
<member><literal>'y'</literal></member>
<member><literal>'yes'</literal></member>
<member><literal>'1'</literal></member>
</simplelist>
For the <quote>false</quote> state, the following values can be
used:
<simplelist>
<member><literal>FALSE</literal></member>
<member><literal>'f'</literal></member>
<member><literal>'false'</literal></member>
<member><literal>'n'</literal></member>
<member><literal>'no'</literal></member>
<member><literal>'0'</literal></member>
</simplelist>
Allow leading and trailing whitespace in the input to the boolean type. Also, add explicit casts between boolean and text/varchar. Both of these changes are for conformance with SQL:2003. Update the regression tests, bump the catversion.
2007-06-02 01:40:19 +02:00
Leading and trailing whitespace is ignored. Using the key words
<literal>TRUE</literal> and <literal>FALSE</literal> is preferred
(and <acronym>SQL</acronym>-compliant).
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 :()
1999-08-06 15:43:42 +02:00
</para>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<example id="datatype-boolean-example">
<title>Using the <type>boolean</type> type</title>
<programlisting>
CREATE TABLE test1 (a boolean, b text);
INSERT INTO test1 VALUES (TRUE, 'sic est');
INSERT INTO test1 VALUES (FALSE, 'non est');
SELECT * FROM test1;
a | b
---+---------
t | sic est
f | non est
SELECT * FROM test1 WHERE a;
a | b
---+---------
t | sic est
</programlisting>
</example>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<xref linkend="datatype-boolean-example"> shows that
<type>boolean</type> values are output using the letters
<literal>t</literal> and <literal>f</literal>.
</para>
<para>
<type>boolean</type> uses 1 byte of storage.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect1>
Support enum data types. Along the way, use macros for the values of pg_type.typtype whereever practical. Tom Dunstan, with some kibitzing from Tom Lane.
2007-04-02 05:49:42 +02:00
<sect1 id="datatype-enum">
<title>Enumerated Types</title>
<indexterm zone="datatype-enum">
<primary>data type</primary>
<secondary>enumerated (enum)</secondary>
</indexterm>
<para>
Enumerated (enum) types are data types that
are comprised of a static, predefined set of values with a
specific order. They are equivalent to the <type>enum</type>
types in a number of programming languages. An example of an enum
type might be the days of the week, or a set of status values for
a piece of data.
</para>
<sect2>
<title>Declaration of Enumerated Types</title>
<para>
Enum types are created using the <xref
linkend="sql-createtype" endterm="sql-createtype-title"> command,
for example:
<programlisting>
CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy');
</programlisting>
Once created, the enum type can be used in table and function
definitions much like any other type:
</para>
<example>
<title>Basic Enum Usage</title>
<programlisting>
CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy');
CREATE TABLE person (
name text,
current_mood mood
);
INSERT INTO person VALUES ('Moe', 'happy');
SELECT * FROM person WHERE current_mood = 'happy';
name | current_mood
------+--------------
Moe | happy
(1 row)
</programlisting>
</example>
</sect2>
<sect2>
<title>Ordering</title>
<para>
The ordering of the values in an enum type is the
order in which the values were listed when the type was declared.
All standard comparison operators and related
aggregate functions are supported for enums. For example:
</para>
<example>
<title>Enum Ordering</title>
<programlisting>
INSERT INTO person VALUES ('Larry', 'sad');
INSERT INTO person VALUES ('Curly', 'ok');
SELECT * FROM person WHERE current_mood > 'sad';
name | current_mood
-------+--------------
Moe | happy
Curly | ok
(2 rows)
SELECT * FROM person WHERE current_mood > 'sad' ORDER BY current_mood;
name | current_mood
-------+--------------
Curly | ok
Moe | happy
(2 rows)
SELECT name FROM person
WHERE current_mood = (SELECT MIN(current_mood) FROM person);
name
-------
Larry
(1 row)
</programlisting>
</example>
</sect2>
<sect2>
<title>Type Safety</title>
<para>
Enumerated types are completely separate data types and may not
be compared with each other.
</para>
<example>
<title>Lack of Casting</title>
<programlisting>
CREATE TYPE happiness AS ENUM ('happy', 'very happy', 'ecstatic');
CREATE TABLE holidays (
num_weeks int,
happiness happiness
);
INSERT INTO holidays(num_weeks,happiness) VALUES (4, 'happy');
INSERT INTO holidays(num_weeks,happiness) VALUES (6, 'very happy');
INSERT INTO holidays(num_weeks,happiness) VALUES (8, 'ecstatic');
INSERT INTO holidays(num_weeks,happiness) VALUES (2, 'sad');
ERROR: invalid input value for enum happiness: "sad"
SELECT person.name, holidays.num_weeks FROM person, holidays
WHERE person.current_mood = holidays.happiness;
ERROR: operator does not exist: mood = happiness
</programlisting>
</example>
<para>
If you really need to do something like that, you can either
write a custom operator or add explicit casts to your query:
</para>
<example>
<title>Comparing Different Enums by Casting to Text</title>
<programlisting>
SELECT person.name, holidays.num_weeks FROM person, holidays
WHERE person.current_mood::text = holidays.happiness::text;
name | num_weeks
------+-----------
Moe | 4
(1 row)
</programlisting>
</example>
</sect2>
<sect2>
<title>Implementation Details</title>
<para>
An enum value occupies four bytes on disk. The length of an enum
value's textual label is limited by the <symbol>NAMEDATALEN</symbol>
setting compiled into <productname>PostgreSQL</productname>; in standard
builds this means at most 63 bytes.
</para>
<para>
Enum labels are case sensitive, so
<type>'happy'</type> is not the same as <type>'HAPPY'</type>.
Spaces in the labels are significant, too.
</para>
</sect2>
</sect1>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-geometric">
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 :()
1999-08-06 15:43:42 +02:00
<title>Geometric Types</title>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
Geometric data types represent two-dimensional spatial
objects. <xref linkend="datatype-geo-table"> shows the geometric
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
types available in <productname>PostgreSQL</productname>. The
most fundamental type, the point, forms the basis for all of the
other types.
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 :()
1999-08-06 15:43:42 +02:00
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-geo-table">
Alter documentation of boolean type, add example. Someone figured that it wasn't clear that the "boolean type" was actually called "boolean". Add tip about "casting" booleans using CASE. Spell check whole file.
2001-02-14 20:37:26 +01:00
<title>Geometric Types</title>
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 :()
1999-08-06 15:43:42 +02:00
<tgroup cols="4">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
<entry>Representation</entry>
<entry>Description</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
<tbody>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>point</type></entry>
<entry>16 bytes</entry>
<entry>Point on the plane</entry>
<entry>(x,y)</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>line</type></entry>
<entry>32 bytes</entry>
<entry>Infinite line (not fully implemented)</entry>
<entry>((x1,y1),(x2,y2))</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>lseg</type></entry>
<entry>32 bytes</entry>
<entry>Finite line segment</entry>
<entry>((x1,y1),(x2,y2))</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>box</type></entry>
<entry>32 bytes</entry>
<entry>Rectangular box</entry>
<entry>((x1,y1),(x2,y2))</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>path</type></entry>
<entry>16+16n bytes</entry>
<entry>Closed path (similar to polygon)</entry>
<entry>((x1,y1),...)</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>path</type></entry>
<entry>16+16n bytes</entry>
<entry>Open path</entry>
<entry>[(x1,y1),...]</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>polygon</type></entry>
<entry>40+16n bytes</entry>
<entry>Polygon (similar to closed path)</entry>
<entry>((x1,y1),...)</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>circle</type></entry>
<entry>24 bytes</entry>
<entry>Circle</entry>
More < and > cleanups converted to ampersands.
2005-01-22 23:56:36 +01:00
<entry>&lt;(x,y),r&gt; (center and radius)</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</tbody>
</tgroup>
</table>
<para>
A rich set of functions and operators is available to perform various geometric
operations such as scaling, translation, rotation, and determining
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
intersections. They are explained in <xref linkend="functions-geometry">.
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 :()
1999-08-06 15:43:42 +02:00
</para>
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Points</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>point</primary>
</indexterm>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
<para>
Points are the fundamental two-dimensional building block for geometric types.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Values of type <type>point</type> are specified using the following syntax:
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
( <replaceable>x</replaceable> , <replaceable>y</replaceable> )
<replaceable>x</replaceable> , <replaceable>y</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where <replaceable>x</> and <replaceable>y</> are the respective
coordinates as floating-point numbers.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Line Segments</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>lseg</primary>
</indexterm>
<indexterm>
<primary>line segment</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Line segments (<type>lseg</type>) are represented by pairs of points.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Values of type <type>lseg</type> are specified using the following syntax:
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )
<replaceable>x1</replaceable> , <replaceable>y1</replaceable> , <replaceable>x2</replaceable> , <replaceable>y2</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where
<literal>(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)</literal>
and
<literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>
are the end points of the line segment.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Boxes</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>box (data type)</primary>
</indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<indexterm>
<primary>rectangle</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Replace incorrect uses of 'which' with 'that'. (so-called "wicked which")
2000-12-22 19:57:50 +01:00
Boxes are represented by pairs of points that are opposite
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 :()
1999-08-06 15:43:42 +02:00
corners of the box.
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
Values of type <type>box</type> are specified using the following syntax:
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> )
<replaceable>x1</replaceable> , <replaceable>y1</replaceable> , <replaceable>x2</replaceable> , <replaceable>y2</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where
<literal>(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)</literal>
and
<literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
are any two opposite corners of the box.
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<para>
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 :()
1999-08-06 15:43:42 +02:00
Boxes are output using the first syntax.
The corners are reordered on input to store
BOX documentation disagreed with code about corner order.
2001-03-10 22:16:32 +01:00
the upper right corner, then the lower left corner.
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 :()
1999-08-06 15:43:42 +02:00
Other corners of the box can be entered, but the lower
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
left and upper right corners are determined from the input and stored.
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 :()
1999-08-06 15:43:42 +02:00
</para>
</sect2>
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Paths</title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>path (data type)</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
Paths are represented by lists of connected points. Paths can be
Replace ASCII-quotes with proper markup.
2001-09-13 17:55:24 +02:00
<firstterm>open</firstterm>, where
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
the first and last points in the list are not considered connected, or
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<firstterm>closed</firstterm>,
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
where the first and last points are considered connected.
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 :()
1999-08-06 15:43:42 +02:00
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Values of type <type>path</type> are specified using the following syntax:
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 :()
1999-08-06 15:43:42 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) )
[ ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) ]
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> , ... , <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
<replaceable>x1</replaceable> , <replaceable>y1</replaceable> , ... , <replaceable>xn</replaceable> , <replaceable>yn</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where the points are the end points of the line segments
comprising the path. Square brackets (<literal>[]</>) indicate
an open path, while parentheses (<literal>()</>) indicate a
closed path.
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<para>
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 :()
1999-08-06 15:43:42 +02:00
Paths are output using the first syntax.
</para>
</sect2>
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Polygons</title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>polygon</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
Polygons are represented by lists of points (the vertexes of the
polygon). Polygons should probably be
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 :()
1999-08-06 15:43:42 +02:00
considered equivalent to closed paths, but are stored differently
and have their own set of support routines.
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Values of type <type>polygon</type> are specified using the following syntax:
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 :()
1999-08-06 15:43:42 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> ) )
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ... , ( <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> , ... , <replaceable>xn</replaceable> , <replaceable>yn</replaceable> )
<replaceable>x1</replaceable> , <replaceable>y1</replaceable> , ... , <replaceable>xn</replaceable> , <replaceable>yn</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where the points are the end points of the line segments
comprising the boundary of the polygon.
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<para>
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 :()
1999-08-06 15:43:42 +02:00
Polygons are output using the first syntax.
</para>
</sect2>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<sect2>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Circles</title>
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>circle</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Circles are represented by a center point and a radius.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Values of type <type>circle</type> are specified using the following syntax:
SGML source for new documentation.
1998-03-01 09:16:16 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
&lt; ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable> &gt;
( ( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable> )
( <replaceable>x</replaceable> , <replaceable>y</replaceable> ) , <replaceable>r</replaceable>
<replaceable>x</replaceable> , <replaceable>y</replaceable> , <replaceable>r</replaceable>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</synopsis>
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
where
<literal>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</literal>
is the center and <replaceable>r</replaceable> is the radius of the circle.
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
Fixups in content and markup for 7.0 release.
2000-05-02 22:02:03 +02:00
<para>
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 :()
1999-08-06 15:43:42 +02:00
Circles are output using the first syntax.
</para>
</sect2>
</sect1>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-net-types">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Network Address Types</title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-net-types">
<primary>network</primary>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<secondary>data types</secondary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
addresses, as shown in <xref linkend="datatype-net-types-table">. It
is preferable to use these types instead of plain text types to store
network addresses, because
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
these types offer input error checking and several specialized
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
operators and functions (see <xref linkend="functions-net">).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
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 :()
1999-08-06 15:43:42 +02:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<table tocentry="1" id="datatype-net-types-table">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Network Address Types</title>
<tgroup cols="3">
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 :()
1999-08-06 15:43:42 +02:00
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Storage Size</entry>
<entry>Description</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
</thead>
<tbody>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
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 :()
1999-08-06 15:43:42 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>cidr</type></entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>7 or 19 bytes</entry>
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
<entry>IPv4 and IPv6 networks</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
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 :()
1999-08-06 15:43:42 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>inet</type></entry>
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<entry>7 or 19 bytes</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>IPv4 and IPv6 hosts and networks</entry>
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 :()
1999-08-06 15:43:42 +02:00
</row>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>macaddr</type></entry>
<entry>6 bytes</entry>
<entry>MAC addresses</entry>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
</row>
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 :()
1999-08-06 15:43:42 +02:00
</tbody>
</tgroup>
</table>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<para>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
When sorting <type>inet</type> or <type>cidr</type> data types,
IPv4 addresses will always sort before IPv6 addresses, including
IPv4 addresses encapsulated or mapped into IPv6 addresses, such as
::10.2.3.4 or ::ffff::10.4.3.2.
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
</para>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-inet">
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
<title><type>inet</type></title>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>inet (data type)</primary>
</indexterm>
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
<para>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
The <type>inet</type> type holds an IPv4 or IPv6 host address, and
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
optionally the identity of the subnet it is in, all in one field.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The subnet identity is represented by stating how many bits of
the host address represent the network address (the
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<quote>netmask</quote>). If the netmask is 32 and the address is IPv4,
then the value does not indicate a subnet, only a single host.
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
In IPv6, the address length is 128 bits, so 128 bits specify a
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
unique host address. Note that if you
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
want to accept networks only, you should use the
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
<type>cidr</type> type rather than <type>inet</type>.
</para>
<para>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
The input format for this type is
<replaceable class="parameter">address/y</replaceable>
where
<replaceable class="parameter">address</replaceable>
is an IPv4 or IPv6 address and
<replaceable class="parameter">y</replaceable>
is the number of bits in the netmask. If the
<replaceable class="parameter">/y</replaceable>
part is left off, then the
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
netmask is 32 for IPv4 and 128 for IPv6, so the value represents
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
just a single host. On display, the
<replaceable class="parameter">/y</replaceable>
portion is suppressed if the netmask specifies a single host.
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
</para>
</sect2>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-cidr">
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<title><type>cidr</></title>
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 :()
1999-08-06 15:43:42 +02:00
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>cidr</primary>
</indexterm>
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 :()
1999-08-06 15:43:42 +02:00
<para>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
The <type>cidr</type> type holds an IPv4 or IPv6 network specification.
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
Input and output formats follow Classless Internet Domain Routing
conventions.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The format for specifying networks is <replaceable
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
class="parameter">address/y</> where <replaceable
class="parameter">address</> is the network represented as an
IPv4 or IPv6 address, and <replaceable
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
class="parameter">y</> is the number of bits in the netmask. If
Change default output formatting for CIDR to be unabbreviated, per recommendation from Paul Vixie. Add a new abbrev() function to produce abbreviated format as text. No forced initdb, but new function is not available unless you do an initdb or add the pg_proc row manually.
2000-12-22 19:00:24 +01:00
<replaceable class="parameter">y</> is omitted, it is calculated
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
using assumptions from the older classful network numbering system, except
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
that it will be at least large enough to include all of the octets
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
written in the input. It is an error to specify a network address
that has bits set to the right of the specified netmask.
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 :()
1999-08-06 15:43:42 +02:00
</para>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<xref linkend="datatype-net-cidr-table"> shows some examples.
</para>
Include new cidr and inet data types.
1998-10-27 07:14:41 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-net-cidr-table">
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<title><type>cidr</> Type Input Examples</title>
Change default output formatting for CIDR to be unabbreviated, per recommendation from Paul Vixie. Add a new abbrev() function to produce abbreviated format as text. No forced initdb, but new function is not available unless you do an initdb or add the pg_proc row manually.
2000-12-22 19:00:24 +01:00
<tgroup cols="3">
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
<thead>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry><type>cidr</type> Input</entry>
<entry><type>cidr</type> Output</entry>
<entry><literal><function>abbrev</function>(<type>cidr</type>)</literal></entry>
</row>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</thead>
<tbody>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<row>
<entry>192.168.100.128/25</entry>
<entry>192.168.100.128/25</entry>
<entry>192.168.100.128/25</entry>
</row>
<row>
<entry>192.168/24</entry>
<entry>192.168.0.0/24</entry>
<entry>192.168.0/24</entry>
</row>
<row>
<entry>192.168/25</entry>
<entry>192.168.0.0/25</entry>
<entry>192.168.0.0/25</entry>
</row>
<row>
<entry>192.168.1</entry>
<entry>192.168.1.0/24</entry>
<entry>192.168.1/24</entry>
</row>
<row>
<entry>192.168</entry>
<entry>192.168.0.0/24</entry>
<entry>192.168.0/24</entry>
</row>
<row>
<entry>128.1</entry>
<entry>128.1.0.0/16</entry>
<entry>128.1/16</entry>
</row>
<row>
<entry>128</entry>
<entry>128.0.0.0/16</entry>
<entry>128.0/16</entry>
</row>
<row>
<entry>128.1.2</entry>
<entry>128.1.2.0/24</entry>
<entry>128.1.2/24</entry>
</row>
<row>
<entry>10.1.2</entry>
<entry>10.1.2.0/24</entry>
<entry>10.1.2/24</entry>
</row>
<row>
<entry>10.1</entry>
<entry>10.1.0.0/16</entry>
<entry>10.1/16</entry>
</row>
<row>
<entry>10</entry>
<entry>10.0.0.0/8</entry>
<entry>10/8</entry>
</row>
<row>
<entry>10.1.2.3/32</entry>
<entry>10.1.2.3/32</entry>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<entry>10.1.2.3/32</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>2001:4f8:3:ba::/64</entry>
<entry>2001:4f8:3:ba::/64</entry>
<entry>2001:4f8:3:ba::/64</entry>
</row>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128</entry>
<entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128</entry>
<entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1</entry>
</row>
<row>
<entry>::ffff:1.2.3.0/120</entry>
<entry>::ffff:1.2.3.0/120</entry>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<entry>::ffff:1.2.3/120</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
<row>
<entry>::ffff:1.2.3.0/128</entry>
<entry>::ffff:1.2.3.0/128</entry>
Add ipv6 address parsing support to 'inet' and 'cidr' data types. Regression tests for IPv6 operations added. Documentation updated to document IPv6 bits. Stop treating IPv4 as an "unsigned int" and IPv6 as an array of characters. Instead, always use the array of characters so we can have one function fits all. This makes bitncmp(), addressOK(), and several other functions "just work" on both address families. add family() function which returns integer 4 or 6 for IPv4 or IPv6. (See examples below) Note that to add this new function you will need to dump/initdb/reload or find the correct magic to add the function to the postgresql function catalogs. IPv4 addresses always sort before IPv6. On disk we use AF_INET for IPv4, and AF_INET+1 for IPv6 addresses. This prevents the need for a dump and reload, but lets IPv6 parsing work on machines without AF_INET6. To select all IPv4 addresses from a table: select * from foo where family(addr) = 4 ... Order by and other bits should all work. Michael Graff
2003-06-25 00:21:24 +02:00
<entry>::ffff:1.2.3.0/128</entry>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
</row>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
</tbody>
</tgroup>
</table>
Mention new AT TIME ZONE feature.
2000-11-11 20:50:31 +01:00
</sect2>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-inet-vs-cidr">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title><type>inet</type> vs. <type>cidr</type></title>
Update some info, especially the CIDR/INET data types.
1998-12-18 17:11:12 +01:00
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 :()
1999-08-06 15:43:42 +02:00
<para>
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
The essential difference between <type>inet</type> and <type>cidr</type>
data types is that <type>inet</type> accepts values with nonzero bits to
the right of the netmask, whereas <type>cidr</type> does not.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
</para>
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
<tip>
<para>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
If you do not like the output format for <type>inet</type> or
<type>cidr</type> values, try the functions <function>host</>,
<function>text</>, and <function>abbrev</>.
</para>
Adjust INET/CIDR display conventions and reimplement some INET/CIDR functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
2000-11-10 21:13:27 +01:00
</tip>
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 :()
1999-08-06 15:43:42 +02:00
</sect2>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect2 id="datatype-macaddr">
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<title><type>macaddr</></>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm>
<primary>macaddr (data type)</primary>
</indexterm>
<indexterm>
<primary>MAC address</primary>
<see>macaddr</see>
</indexterm>
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
<para>
The <type>macaddr</> type stores MAC addresses, i.e., Ethernet
card hardware addresses (although MAC addresses are used for
other purposes as well). Input is accepted in various customary
Bunch of copy fitting and style sheet tweakage to get decent looking print output (from pdfjadetex). Also updated instructions to install documentation processing toolchain.
2001-10-09 20:46:00 +02:00
formats, including
<simplelist>
<member><literal>'08002b:010203'</></member>
<member><literal>'08002b-010203'</></member>
<member><literal>'0800.2b01.0203'</></member>
<member><literal>'08-00-2b-01-02-03'</></member>
<member><literal>'08:00:2b:01:02:03'</></member>
</simplelist>
which would all specify the same
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
address. Upper and lower case is accepted for the digits
<literal>a</> through <literal>f</>. Output is always in the
A small pass of docs review and copy-editing.
2004-12-23 06:37:40 +01:00
last of the forms shown.
Convert macaddr documentation to DocBook, update outdated information.
2000-10-04 17:47:45 +02:00
</para>
</sect2>
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 :()
1999-08-06 15:43:42 +02:00
</sect1>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<sect1 id="datatype-bit">
<title>Bit String Types</title>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<indexterm zone="datatype-bit">
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>bit string</primary>
Add index. Only some parts of the manual set have index entries so far...
2001-05-13 00:51:36 +02:00
<secondary>data type</secondary>
</indexterm>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<para>
Bit strings are strings of 1's and 0's. They can be used to store
or visualize bit masks. There are two SQL bit types:
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<type>bit(<replaceable>n</replaceable>)</type> and <type>bit
varying(<replaceable>n</replaceable>)</type>, where
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
<replaceable>n</replaceable> is a positive integer.
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<type>bit</type> type data must match the length
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
<replaceable>n</replaceable> exactly; it is an error to attempt to
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
store shorter or longer bit strings. <type>bit varying</type> data is
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
of variable length up to the maximum length
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
<replaceable>n</replaceable>; longer strings will be rejected.
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
Writing <type>bit</type> without a length is equivalent to
<literal>bit(1)</literal>, while <type>bit varying</type> without a length
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
specification means unlimited length.
</para>
<note>
<para>
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
If one explicitly casts a bit-string value to
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<type>bit(<replaceable>n</>)</type>, it will be truncated or
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
zero-padded on the right to be exactly <replaceable>n</> bits,
without raising an error. Similarly,
if one explicitly casts a bit-string value to
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<type>bit varying(<replaceable>n</>)</type>, it will be truncated
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
on the right if it is more than <replaceable>n</> bits.
</para>
</note>
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
<para>
Refer to <xref
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
linkend="sql-syntax-bit-strings"> for information about the syntax
of bit string constants. Bit-logical operators and string
manipulation functions are available; see <xref
Represent type-specific length coercion functions as pg_cast entries, eliminating the former hard-wired convention about their names. Allow pg_cast entries to represent both type coercion and length coercion in a single step --- this is represented by a function that takes an extra typmod argument, just like a length coercion function. This nicely merges the type and length coercion mechanisms into something at least a little cleaner than we had before. Make use of the single- coercion-step behavior to fix integer-to-bit coercion so that coercing to bit(n) yields the rightmost n bits of the integer instead of the leftmost n bits. This should fix recurrent complaints about the odd behavior of this coercion. Clean up the documentation of the bit string functions, and try to put it where people might actually find it. Also, get rid of the unreliable heuristics in ruleutils.c about whether to display nested coercion steps; instead require parse_coerce.c to label them properly in the first place.
2004-06-16 03:27:00 +02:00
linkend="functions-bitstring">.
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</para>
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
<example>
<title>Using the bit string types</title>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
<programlisting>
CREATE TABLE test (a BIT(3), b BIT VARYING(5));
INSERT INTO test VALUES (B'101', B'00');
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
INSERT INTO test VALUES (B'10', B'101');
<computeroutput>
Update obsolete examples of error messages; various other minor editing.
2003-09-13 00:17:24 +02:00
ERROR: bit string length 2 does not match type bit(3)
Extend pg_cast castimplicit column to a three-way value; this allows us to be flexible about assignment casts without introducing ambiguity in operator/function resolution. Introduce a well-defined promotion hierarchy for numeric datatypes (int2->int4->int8->numeric->float4->float8). Change make_const to initially label numeric literals as int4, int8, or numeric (never float8 anymore). Explicitly mark Func and RelabelType nodes to indicate whether they came from a function call, explicit cast, or implicit cast; use this to do reverse-listing more accurately and without so many heuristics. Explicit casts to char, varchar, bit, varbit will truncate or pad without raising an error (the pre-7.2 behavior), while assigning to a column without any explicit cast will still raise an error for wrong-length data like 7.3. This more nearly follows the SQL spec than 7.2 behavior (we should be reporting a 'completion condition' in the explicit-cast cases, but we have no mechanism for that, so just do silent truncation). Fix some problems with enforcement of typmod for array elements; it didn't work at all in 'UPDATE ... SET array[n] = foo', for example. Provide a generalized array_length_coerce() function to replace the specialized per-array-type functions that used to be needed (and were missing for NUMERIC as well as all the datetime types). Add missing conversions int8<->float4, text<->numeric, oid<->int8. initdb forced.
2002-09-18 23:35:25 +02:00
</computeroutput>
INSERT INTO test VALUES (B'10'::bit(3), B'101');
SELECT * FROM test;
<computeroutput>
a | b
-----+-----
101 | 00
100 | 101
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
</computeroutput>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</programlisting>
Make bit and bit varying types reject too long input. (They already tried to do that, but inconsistently.) Make bit type reject too short input, too, per SQL. Since it no longer zero pads, 'zpbit*' has been renamed to 'bit*' in the source, hence initdb.
2001-05-22 18:37:17 +02:00
</example>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
Fix some now-obsolete comments about the space used by various data types.
2007-04-06 21:22:38 +02:00
<para>
A bit string value requires 1 byte for each group of 8 bits, plus
5 or 8 bytes overhead depending on the length of the string
(but long values may be compressed or moved out-of-line, as explained
in <xref linkend="datatype-character"> for character strings).
</para>
Add information about bit types. Adjust some other things to promote SQL type names over internal type names.
2001-01-13 19:34:51 +01:00
</sect1>
Documentation for UUID type
2007-04-20 23:51:46 +02:00
<sect1 id="datatype-uuid">
<title><acronym>UUID</acronym> Type</title>
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
<indexterm zone="datatype-uuid">
Documentation for UUID type
2007-04-20 23:51:46 +02:00
<primary>UUID</primary>
</indexterm>
<para>
The data type <type>uuid</type> stores Universally Unique
Identifiers (UUID) as per RFC 4122, ISO/IEC 9834-8:2005, and
related standards. (Some systems refer to this data type as
globally unique
identifier/GUID<indexterm><primary>GUID</primary></indexterm>
instead.) Such an identifier is a 128-bit quantity that is
generated by a suitable algorithm so that it is very unlikely to
be generated by anyone else in the known universe using the same
algorithm. Therefore, for distributed systems, these identifiers
provide a better uniqueness guarantee than that which can be
achieved using sequence generators, which are only unique within a
single database.
</para>
<para>
A UUID is written as a sequence of lower-case hexadecimal digits,
in several groups separated by hyphens, specifically a group of 8
digits followed by three groups of 4 digits followed by a group of
12 digits, for a total of 32 digits representing the 128 bits. An
example of a UUID in this standard form is:
<programlisting>
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
</programlisting>
PostgreSQL also accepts the following alternative forms for input:
use of upper-case digits, the standard format surrounded by
braces, and omitting the hyphens. Examples are:
<programlisting>
A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}
a0eebc999c0b4ef8bb6d6bb9bd380a11
</programlisting>
Output is always in the standard form.
</para>
Contrib module uuid-ossp for generating UUID values using the OSSP UUID library. New configure option --with-ossp-uuid to activate.
2007-04-21 19:26:18 +02:00
<para>
To generate UUIDs, the contrib module <literal>uuid-ossp</literal>
provides functions that implement the standard algorithms.
Alternatively, UUIDs could be generated by client applications or
other libraries invoked through a server-side function.
</para>
Documentation for UUID type
2007-04-20 23:51:46 +02:00
</sect1>
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
<sect1 id="datatype-xml">
<title><acronym>XML</> Type</title>
<indexterm zone="datatype-xml">
<primary>XML</primary>
</indexterm>
<para>
The data type <type>xml</type> can be used to store XML data. Its
advantage over storing XML data in a <type>text</type> field is that it
checks the input values for well-formedness, and there are support
functions to perform type-safe operations on it; see <xref
Improve documentation/warning when --with-libxml is not used in the installation.
2007-04-05 03:46:27 +02:00
linkend="functions-xml">. Use of this data type requires the
installation to have been built with <command>configure
--with-libxml</>.
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
</para>
<para>
Improve documentation/warning when --with-libxml is not used in the installation.
2007-04-05 03:46:27 +02:00
The <type>xml</type> type can store well-formed
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
<quote>documents</quote>, as defined by the XML standard, as well
as <quote>content</quote> fragments, which are defined by the
production <literal>XMLDecl? content</literal> in the XML
standard. Roughly, this means that content fragments can have
more than one top-level element or character node. The expression
<literal><replaceable>xmlvalue</replaceable> IS DOCUMENT</literal>
can be used to evaluate whether a particular <type>xml</type>
value is a full document or only a content fragment.
</para>
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
<sect2>
<title>Creating XML Values</title>
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
<para>
To produce a value of type <type>xml</type> from character data,
use the function
<function>xmlparse</function>:<indexterm><primary>xmlparse</primary></indexterm>
<synopsis>
XMLPARSE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable>)
</synopsis>
Examples:
<programlisting><![CDATA[
XMLPARSE (DOCUMENT '<?xml version="1.0"?><book><title>Manual</title><chapter>...</chapter><book>')
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
XMLPARSE (CONTENT 'abc<foo>bar</foo><bar>foo</bar>')
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
]]></programlisting>
While this is the only way to convert character strings into XML
values according to the SQL standard, the PostgreSQL-specific
syntaxes:
<programlisting><![CDATA[
xml '<foo>bar</foo>'
'<foo>bar</foo>'::xml
]]></programlisting>
can also be used.
</para>
<para>
The <type>xml</type> type does not validate its input values
against a possibly included document type declaration
(DTD).<indexterm><primary>DTD</primary></indexterm>
</para>
<para>
The inverse operation, producing character string type values from
<type>xml</type>, uses the function
<function>xmlserialize</function>:<indexterm><primary>xmlserialize</primary></indexterm>
<synopsis>
XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <replaceable>type</replaceable> )
</synopsis>
<replaceable>type</replaceable> can be one of
<type>character</type>, <type>character varying</type>, or
<type>text</type> (or an alias name for those). Again, according
to the SQL standard, this is the only way to convert between type
<type>xml</type> and character types, but PostgreSQL also allows
you to simply cast the value.
</para>
<para>
When character string values are cast to or from type
<type>xml</type> without going through <type>XMLPARSE</type> or
<type>XMLSERIALIZE</type>, respectively, the choice of
<literal>DOCUMENT</literal> versus <literal>CONTENT</literal> is
determined by the <quote>XML option</quote>
<indexterm><primary>XML option</primary></indexterm>
session configuration parameter, which can be set using the
standard command
<synopsis>
SET XML OPTION { DOCUMENT | CONTENT };
</synopsis>
or the more PostgreSQL-like syntax
<synopsis>
SET xmloption TO { DOCUMENT | CONTENT };
</synopsis>
The default is <literal>CONTENT</literal>, so all forms of XML
data are allowed.
</para>
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
</sect2>
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
<sect2>
<title>Encoding Handling</title>
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
<para>
Care must be taken when dealing with multiple character encodings
on the client, server, and in the XML data passed through them.
When using the text mode to pass queries to the server and query
results to the client (which is the normal mode), PostgreSQL
converts all character data passed between the client and the
server and vice versa to the character encoding of the respective
end; see <xref linkend="multibyte">. This includes string
representations of XML values, such as in the above examples.
This would ordinarily mean that encoding declarations contained in
XML data might become invalid as the character data is converted
to other encodings while travelling between client and server,
while the embedded encoding declaration is not changed. To cope
with this behavior, an encoding declaration contained in a
character string presented for input to the <type>xml</type> type
is <emphasis>ignored</emphasis>, and the content is always assumed
to be in the current server encoding. Consequently, for correct
processing, such character strings of XML data must be sent off
from the client in the current client encoding. It is the
responsibility of the client to either convert the document to the
current client encoding before sending it off to the server or to
adjust the client encoding appropriately. On output, values of
type <type>xml</type> will not have an encoding declaration, and
clients must assume that the data is in the current client
encoding.
</para>
<para>
When using the binary mode to pass query parameters to the server
Fix some typos in the documentation. Patch from Brian Gough. Backport the relevant fixes to 8.2 as well.
2007-05-03 17:05:56 +02:00
and query results back to the client, no character set conversion
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
is performed, so the situation is different. In this case, an
encoding declaration in the XML data will be observed, and if it
is absent, the data will be assumed to be in UTF-8 (as required by
the XML standard; note that PostgreSQL does not support UTF-16 at
all). On output, data will have an encoding declaration
specifying the client encoding, unless the client encoding is
UTF-8, in which case it will be omitted.
</para>
<para>
Needless to say, processing XML data with PostgreSQL will be less
error-prone and more efficient if data encoding, client encoding,
and server encoding are the same. Since XML data is internally
processed in UTF-8, computations will be most efficient if the
server encoding is also UTF-8.
</para>
XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', '<?xml version="1.0"?><a /><b />'); // now XML datum is always wrapped with dummy <x>...</x>, XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself.
2007-05-21 19:10:29 +02:00
</sect2>
<sect2>
<title>Accessing XML Values</title>
<para>
The <type>xml</type> data type is unusual in that it does not
provide any comparison operators. This is because there is no
well-defined and universally useful comparison algorithm for XML
data. One consequence of this is that you cannot retrieve rows by
comparing an <type>xml</type> column against a search value. XML
values should therefore typically be accompanied by a separate key
field such as an ID. An alternative solution for comparing XML
values is to convert them to character strings first, but note
that character string comparison has little to do with a useful
XML comparison method.
</para>
<para>
Since there are no comparison operators for the <type>xml</type>
data type, it is not possible to create an index directly on a
column of this type. If speedy searches in XML data are desired,
possible workarounds would be casting the expression to a
character string type and indexing that, or indexing an XPath
expression. The actual query would of course have to be adjusted
to search by the indexed expression.
</para>
<para>
The full-text search module Tsearch2 could also be used to speed
up full-document searches in XML data. The necessary
preprocessing support is, however, not available in the PostgreSQL
distribution in this release.
</para>
</sect2>
Put documentation on XML data type and functions in better positions. Add some index terms.
2007-04-02 17:27:02 +02:00
</sect1>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
&array;
Some preliminary documentation for composite-type stuff.
2004-06-07 06:04:47 +02:00
&rowtypes;
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
<sect1 id="datatype-oid">
<title>Object Identifier Types</title>
<indexterm zone="datatype-oid">
<primary>object identifier</primary>
<secondary>data type</secondary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>oid</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regproc</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regprocedure</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regoper</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regoperator</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regclass</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regtype</primary>
</indexterm>
Tsearch2 functionality migrates to core. The bulk of this work is by Oleg Bartunov and Teodor Sigaev, but I did a lot of editorializing, so anything that's broken is probably my fault. Documentation is nonexistent as yet, but let's land the patch so we can get some portability testing done.
2007-08-21 03:11:32 +02:00
<indexterm zone="datatype-oid">
<primary>regconfig</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>regdictionary</primary>
</indexterm>
Updates for schema features.
2002-04-25 22:14:43 +02:00
<indexterm zone="datatype-oid">
<primary>xid</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>cid</primary>
</indexterm>
<indexterm zone="datatype-oid">
<primary>tid</primary>
</indexterm>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
<para>
Object identifiers (OIDs) are used internally by
This patch adds a new GUC var, "default_with_oids", which follows the proposal for eventually deprecating OIDs on user tables that I posted earlier to pgsql-hackers. pg_dump now always specifies WITH OIDS or WITHOUT OIDS when dumping a table. The documentation has been updated. Neil Conway
2003-12-01 23:08:02 +01:00
<productname>PostgreSQL</productname> as primary keys for various
Make default_with_oids default to false -- user-created tables will now no longer include OIDs, unless WITH OIDS is specified or the default_with_oids configuration parameter is enabled. Update the docs accordingly.
2005-03-13 10:36:31 +01:00
system tables. OIDs are not added to user-created tables, unless
<literal>WITH OIDS</literal> is specified when the table is
created, or the <xref linkend="guc-default-with-oids">
configuration variable is enabled. Type <type>oid</> represents
an object identifier. There are also several alias types for
<type>oid</>: <type>regproc</>, <type>regprocedure</>,
Tsearch2 functionality migrates to core. The bulk of this work is by Oleg Bartunov and Teodor Sigaev, but I did a lot of editorializing, so anything that's broken is probably my fault. Documentation is nonexistent as yet, but let's land the patch so we can get some portability testing done.
2007-08-21 03:11:32 +02:00
<type>regoper</>, <type>regoperator</>, <type>regclass</>,
<type>regtype</>, <type>regconfig</>, and <type>regdictionary</>.
<xref linkend="datatype-oid-table"> shows an overview.
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</para>
<para>
This patch adds a new GUC var, "default_with_oids", which follows the proposal for eventually deprecating OIDs on user tables that I posted earlier to pgsql-hackers. pg_dump now always specifies WITH OIDS or WITHOUT OIDS when dumping a table. The documentation has been updated. Neil Conway
2003-12-01 23:08:02 +01:00
The <type>oid</> type is currently implemented as an unsigned
four-byte integer. Therefore, it is not large enough to provide
database-wide uniqueness in large databases, or even in large
individual tables. So, using a user-created table's OID column as
a primary key is discouraged. OIDs are best used only for
references to system tables.
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The <type>oid</> type itself has few operations beyond comparison.
Make default_with_oids default to false -- user-created tables will now no longer include OIDs, unless WITH OIDS is specified or the default_with_oids configuration parameter is enabled. Update the docs accordingly.
2005-03-13 10:36:31 +01:00
It can be cast to integer, however, and then manipulated using the
standard integer operators. (Beware of possible
signed-versus-unsigned confusion if you do this.)
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</para>
<para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
The OID alias types have no operations of their own except
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
for specialized input and output routines. These routines are able
to accept and display symbolic names for system objects, rather than
the raw numeric value that type <type>oid</> would use. The alias
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
types allow simplified lookup of OID values for objects. For example,
to examine the <structname>pg_attribute</> rows related to a table
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
<literal>mytable</>, one could write:
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
<programlisting>
SELECT * FROM pg_attribute WHERE attrelid = 'mytable'::regclass;
</programlisting>
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
rather than:
Some small docs improvements motivated by reading the comments for the 7.4 7.4 interactive docs.
2005-01-08 06:19:18 +01:00
<programlisting>
SELECT * FROM pg_attribute
WHERE attrelid = (SELECT oid FROM pg_class WHERE relname = 'mytable');
</programlisting>
While that doesn't look all that bad by itself, it's still oversimplified.
A far more complicated sub-select would be needed to
select the right OID if there are multiple tables named
<literal>mytable</> in different schemas.
The <type>regclass</> input converter handles the table lookup according
to the schema path setting, and so it does the <quote>right thing</>
automatically. Similarly, casting a table's OID to
<type>regclass</> is handy for symbolic display of a numeric OID.
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-oid-table">
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
<title>Object Identifier Types</title>
<tgroup cols="4">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>References</entry>
<entry>Description</entry>
<entry>Value Example</entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
</thead>
<tbody>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>oid</></entry>
<entry>any</entry>
<entry>numeric object identifier</entry>
<entry><literal>564182</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regproc</></entry>
<entry><structname>pg_proc</></entry>
<entry>function name</entry>
<entry><literal>sum</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regprocedure</></entry>
<entry><structname>pg_proc</></entry>
<entry>function with argument types</entry>
<entry><literal>sum(int4)</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regoper</></entry>
<entry><structname>pg_operator</></entry>
<entry>operator name</entry>
<entry><literal>+</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regoperator</></entry>
<entry><structname>pg_operator</></entry>
<entry>operator with argument types</entry>
<entry><literal>*(integer,integer)</> or <literal>-(NONE,integer)</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regclass</></entry>
<entry><structname>pg_class</></entry>
<entry>relation name</entry>
<entry><literal>pg_type</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>regtype</></entry>
<entry><structname>pg_type</></entry>
<entry>data type name</entry>
<entry><literal>integer</></entry>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</row>
Tsearch2 functionality migrates to core. The bulk of this work is by Oleg Bartunov and Teodor Sigaev, but I did a lot of editorializing, so anything that's broken is probably my fault. Documentation is nonexistent as yet, but let's land the patch so we can get some portability testing done.
2007-08-21 03:11:32 +02:00
<row>
<entry><type>regconfig</></entry>
<entry><structname>pg_ts_config</></entry>
<entry>text search configuration</entry>
<entry><literal>english</></entry>
</row>
<row>
<entry><type>regdictionary</></entry>
<entry><structname>pg_ts_dict</></entry>
<entry>text search dictionary</entry>
<entry><literal>simple</></entry>
</row>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</tbody>
</tgroup>
</table>
<para>
Updates for schema features.
2002-04-25 22:14:43 +02:00
All of the OID alias types accept schema-qualified names, and will
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
display schema-qualified names on output if the object would not
be found in the current search path without being qualified.
The <type>regproc</> and <type>regoper</> alias types will only
accept input names that are unique (not overloaded), so they are
of limited use; for most uses <type>regprocedure</> or
<type>regoperator</> is more appropriate. For <type>regoperator</>,
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
unary operators are identified by writing <literal>NONE</> for the unused
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
operand.
</para>
Change nextval and other sequence functions to specify their sequence argument as a 'regclass' value instead of a text string. The frontend conversion of text string to pg_class OID is now encapsulated as an implicitly-invocable coercion from text to regclass. This provides backwards compatibility to the old behavior when the sequence argument is explicitly typed as 'text'. When the argument is just an unadorned literal string, it will be taken as 'regclass', which means that the stored representation will be an OID. This solves longstanding problems with renaming sequences that are referenced in default expressions, as well as new-in-8.1 problems with renaming such sequences' schemas or moving them to another schema. All per recent discussion. Along the way, fix some rather serious problems in dbmirror's support for mirroring sequence operations (int4 vs int8 confusion for instance).
2005-10-03 01:50:16 +02:00
<para>
An additional property of the OID alias types is that if a
constant of one of these types appears in a stored expression
(such as a column default expression or view), it creates a dependency
on the referenced object. For example, if a column has a default
expression <literal>nextval('my_seq'::regclass)</>,
<productname>PostgreSQL</productname>
understands that the default expression depends on the sequence
<literal>my_seq</>; the system will not let the sequence be dropped
without first removing the default expression.
</para>
Updates for schema features.
2002-04-25 22:14:43 +02:00
<para>
Another identifier type used by the system is <type>xid</>, or transaction
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
(abbreviated <abbrev>xact</>) identifier. This is the data type of the system columns
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<structfield>xmin</> and <structfield>xmax</>. Transaction identifiers are 32-bit quantities.
Updates for schema features.
2002-04-25 22:14:43 +02:00
</para>
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
A third identifier type used by the system is <type>cid</>, or
command identifier. This is the data type of the system columns
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<structfield>cmin</> and <structfield>cmax</>. Command identifiers are also 32-bit quantities.
Updates for schema features.
2002-04-25 22:14:43 +02:00
</para>
<para>
A final identifier type used by the system is <type>tid</>, or tuple
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
identifier (row identifier). This is the data type of the system column
Updates for schema features.
2002-04-25 22:14:43 +02:00
<structfield>ctid</>. A tuple ID is a pair
(block number, tuple index within block) that identifies the
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
physical location of the row within its table.
Updates for schema features.
2002-04-25 22:14:43 +02:00
</para>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<para>
(The system columns are further explained in <xref
linkend="ddl-system-columns">.)
</para>
Implement types regprocedure, regoper, regoperator, regclass, regtype per pghackers discussion. Add some more typsanity tests, and clean up some problems exposed thereby (broken or missing array types for some built-in types). Also, clean up loose ends from unknownin/out patch.
2002-04-25 04:56:56 +02:00
</sect1>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
<sect1 id="datatype-pseudo">
<title>Pseudo-Types</title>
<indexterm zone="datatype-pseudo">
<primary>record</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>any</primary>
</indexterm>
Fix up text concatenation so that it accepts all the reasonable cases that were accepted by prior Postgres releases. This takes care of the loose end left by the preceding patch to downgrade implicit casts-to-text. To avoid breaking desirable behavior for array concatenation, introduce a new polymorphic pseudo-type "anynonarray" --- the added concatenation operators are actually text || anynonarray and anynonarray || text.
2007-06-07 01:00:50 +02:00
<indexterm zone="datatype-pseudo">
<primary>anyelement</primary>
</indexterm>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
<indexterm zone="datatype-pseudo">
<primary>anyarray</primary>
</indexterm>
Update docs for 7.4 array features and polymorphic functions. This is Joe Conway's patch of 7-Aug plus further editorializing of my own.
2003-08-10 00:50:22 +02:00
<indexterm zone="datatype-pseudo">
Fix up text concatenation so that it accepts all the reasonable cases that were accepted by prior Postgres releases. This takes care of the loose end left by the preceding patch to downgrade implicit casts-to-text. To avoid breaking desirable behavior for array concatenation, introduce a new polymorphic pseudo-type "anynonarray" --- the added concatenation operators are actually text || anynonarray and anynonarray || text.
2007-06-07 01:00:50 +02:00
<primary>anynonarray</primary>
Update docs for 7.4 array features and polymorphic functions. This is Joe Conway's patch of 7-Aug plus further editorializing of my own.
2003-08-10 00:50:22 +02:00
</indexterm>
Support enum data types. Along the way, use macros for the values of pg_type.typtype whereever practical. Tom Dunstan, with some kibitzing from Tom Lane.
2007-04-02 05:49:42 +02:00
<indexterm zone="datatype-pseudo">
<primary>anyenum</primary>
</indexterm>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
<indexterm zone="datatype-pseudo">
<primary>void</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>trigger</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>language_handler</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>cstring</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>internal</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>opaque</primary>
</indexterm>
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
The <productname>PostgreSQL</productname> type system contains a
number of special-purpose entries that are collectively called
<firstterm>pseudo-types</>. A pseudo-type cannot be used as a
column data type, but it can be used to declare a function's
argument or result type. Each of the available pseudo-types is
useful in situations where a function's behavior does not
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
correspond to simply taking or returning a value of a specific
<acronym>SQL</acronym> data type. <xref
linkend="datatype-pseudotypes-table"> lists the existing
pseudo-types.
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<table id="datatype-pseudotypes-table">
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
<title>Pseudo-Types</title>
<tgroup cols="2">
<thead>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry>Name</entry>
<entry>Description</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
</thead>
<tbody>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>any</></entry>
<entry>Indicates that a function accepts any input data type whatever.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>anyarray</></entry>
<entry>Indicates that a function accepts any array data type
(see <xref linkend="extend-types-polymorphic">).</entry>
Update docs for 7.4 array features and polymorphic functions. This is Joe Conway's patch of 7-Aug plus further editorializing of my own.
2003-08-10 00:50:22 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>anyelement</></entry>
<entry>Indicates that a function accepts any data type
(see <xref linkend="extend-types-polymorphic">).</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
Support enum data types. Along the way, use macros for the values of pg_type.typtype whereever practical. Tom Dunstan, with some kibitzing from Tom Lane.
2007-04-02 05:49:42 +02:00
<row>
<entry><type>anyenum</></entry>
<entry>Indicates that a function accepts any enum data type
(see <xref linkend="extend-types-polymorphic"> and
<xref linkend="datatype-enum">).</entry>
</row>
Fix up text concatenation so that it accepts all the reasonable cases that were accepted by prior Postgres releases. This takes care of the loose end left by the preceding patch to downgrade implicit casts-to-text. To avoid breaking desirable behavior for array concatenation, introduce a new polymorphic pseudo-type "anynonarray" --- the added concatenation operators are actually text || anynonarray and anynonarray || text.
2007-06-07 01:00:50 +02:00
<row>
<entry><type>anynonarray</></entry>
<entry>Indicates that a function accepts any non-array data type
(see <xref linkend="extend-types-polymorphic">).</entry>
</row>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>cstring</></entry>
<entry>Indicates that a function accepts or returns a null-terminated C string.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>internal</></entry>
<entry>Indicates that a function accepts or returns a server-internal
data type.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>language_handler</></entry>
<entry>A procedural language call handler is declared to return <type>language_handler</>.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>record</></entry>
<entry>Identifies a function returning an unspecified row type.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>trigger</></entry>
<entry>A trigger function is declared to return <type>trigger.</></entry>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>void</></entry>
<entry>Indicates that a function returns no value.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
<row>
Spell checking, consistent terminology.
2003-11-01 02:56:29 +01:00
<entry><type>opaque</></entry>
<entry>An obsolete type name that formerly served all the above purposes.</entry>
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</row>
</tbody>
</tgroup>
</table>
<para>
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
Functions coded in C (whether built-in or dynamically loaded) can be
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
declared to accept or return any of these pseudo data types. It is up to
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
the function author to ensure that the function will behave safely
when a pseudo-type is used as an argument type.
</para>
<para>
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
Functions coded in procedural languages can use pseudo-types only as
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
allowed by their implementation languages. At present the procedural
languages all forbid use of a pseudo-type as argument type, and allow
Update docs for 7.4 array features and polymorphic functions. This is Joe Conway's patch of 7-Aug plus further editorializing of my own.
2003-08-10 00:50:22 +02:00
only <type>void</> and <type>record</> as a result type (plus
<type>trigger</> when the function is used as a trigger). Some also
Support enum data types. Along the way, use macros for the values of pg_type.typtype whereever practical. Tom Dunstan, with some kibitzing from Tom Lane.
2007-04-02 05:49:42 +02:00
support polymorphic functions using the types <type>anyarray</>,
Fix up text concatenation so that it accepts all the reasonable cases that were accepted by prior Postgres releases. This takes care of the loose end left by the preceding patch to downgrade implicit casts-to-text. To avoid breaking desirable behavior for array concatenation, introduce a new polymorphic pseudo-type "anynonarray" --- the added concatenation operators are actually text || anynonarray and anynonarray || text.
2007-06-07 01:00:50 +02:00
<type>anyelement</>, <type>anyenum</>, and <type>anynonarray</>.
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</para>
<para>
SGML improvements. Neil Conway
2002-11-15 04:11:18 +01:00
The <type>internal</> pseudo-type is used to declare functions
that are meant only to be called internally by the database
system, and not by direct invocation in a <acronym>SQL</acronym>
query. If a function has at least one <type>internal</>-type
argument then it cannot be called from <acronym>SQL</acronym>. To
preserve the type safety of this restriction it is important to
follow this coding rule: do not create any function that is
declared to return <type>internal</> unless it has at least one
<type>internal</> argument.
Add a bunch of pseudo-types to replace the behavior formerly associated with OPAQUE, as per recent pghackers discussion. I still want to do some more work on the 'cstring' pseudo-type, but I'm going to commit the bulk of the changes now before the tree starts shifting under me ...
2002-08-22 02:01:51 +02:00
</para>
</sect1>
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 :()
1999-08-06 15:43:42 +02:00
</chapter>