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/ref/create_table.sgml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

2521 lines
107 KiB
Plaintext
Raw Normal View History

Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<!--
Remove cvs keywords from all files.
2010-09-20 22:08:53 +02:00
doc/src/sgml/ref/create_table.sgml
Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:40 +01:00
PostgreSQL documentation
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
-->
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refentry id="sql-createtable">
doc: Improve DocBook XML validity DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
2014-02-24 03:25:35 +01:00
<indexterm zone="sql-createtable">
<primary>CREATE TABLE</primary>
</indexterm>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<refmeta>
Remove unnecessary xref endterm attributes and title ids The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
2010-04-03 09:23:02 +02:00
<refentrytitle>CREATE TABLE</refentrytitle>
Set SQL man pages to be section 7 by default, and only transform them to another section if required by the platform (instead of the old way of building them in section "l" and always transforming them to the platform-specific section). This speeds up the installation on common platforms, and it avoids some funny business with the man page tools and build process.
2008-11-14 11:22:48 +01:00
<manvolnum>7</manvolnum>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<refnamediv>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<refname>CREATE TABLE</refname>
<refpurpose>define a new table</refpurpose>
Clean up to ensure tag completion as required by the newest versions of Norm's Modular Style Sheets and jade/docbook. From Vince Vielhaber <vev@michvhf.com>.
1998-12-29 03:24:47 +01:00
</refnamediv>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<refsynopsisdiv>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<synopsis>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable> ( [
Support writing "CREATE/ALTER TABLE ... SET STORAGE DEFAULT". We already allow explicitly writing DEFAULT for SET COMPRESSION, so it seems a bit inflexible and non-orthogonal to not have it for STORAGE. Aleksander Alekseev Discussion: https://postgr.es/m/CAJ7c6TMX9ui+6y3TQFaXJYVpZyBukvqhQbVDJ8OUokeLRhtnpA@mail.gmail.com
2022-11-11 00:20:49 +01:00
{ <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } ] [ COMPRESSION <replaceable>compression_method</replaceable> ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
Brief note about sequence cache not being cleared in other backends. Actually clear the cache in the backend making the alteration. This follows in the footsteps of setval(). Rod Taylor
2003-06-12 09:49:43 +02:00
| <replaceable>table_constraint</replaceable>
Rename the internal structures of the CREATE TABLE (LIKE ...) facility The original implementation of this interpreted it as a kind of "inheritance" facility and named all the internal structures accordingly. This turned out to be very confusing, because it has nothing to do with the INHERITS feature. So rename all the internal parser infrastructure, update the comments, adjust the error messages, and split up the regression tests.
2012-01-07 13:58:13 +01:00
| LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ] }
Make an editorial pass over the reference pages.
2005-11-01 22:09:51 +01:00
[, ... ]
] )
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
[ INHERITS ( <replaceable>parent_table</replaceable> [, ... ] ) ]
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
[ USING <replaceable class="parameter">method</replaceable> ]
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
Code review for ON COMMIT patch. Make the actual on-commit action happen before commit, not after :-( --- the original coding is not only unsafe if an error occurs while it's processing, but it generates an invalid sequence of WAL entries. Resurrect 7.2 logic for deleting items when no longer needed. Use an enum instead of random macros. Editorialize on names used for routines and constants. Teach backend/nodes routines about new field in CreateTable struct. Add a regression test.
2002-11-11 23:19:25 +01:00
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
OF <replaceable class="parameter">type_name</replaceable> [ (
{ <replaceable class="parameter">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
| <replaceable>table_constraint</replaceable> }
[, ... ]
) ]
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
[ USING <replaceable class="parameter">method</replaceable> ]
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
PARTITION OF <replaceable class="parameter">parent_table</replaceable> [ (
{ <replaceable class="parameter">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
| <replaceable>table_constraint</replaceable> }
[, ... ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
) ] { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
[ USING <replaceable class="parameter">method</replaceable> ]
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase>where <replaceable class="parameter">column_constraint</replaceable> is:</phrase>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
{ NOT NULL |
NULL |
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] |
Reclassify DEFAULT as a column_constraint item in the CREATE TABLE syntax. This is how it was documented originally, but several years ago somebody decided that DEFAULT isn't a type of constraint. Well, the grammar thinks it is. The documentation was wrong in two ways: it alleged that DEFAULT had to appear before any other kind of constraint, and it alleged that you can't prefix a DEFAULT clause with a "CONSTRAINT name" clause, when in fact you can. (The latter behavior probably isn't SQL-standard, but our grammar has always allowed it.) This patch responds to Fujii Masao's observation that the ALTER TABLE documentation mistakenly implied that you couldn't include DEFAULT in ALTER TABLE ADD COLUMN; though this isn't the way he proposed fixing it.
2010-12-29 03:38:05 +01:00
DEFAULT <replaceable>default_expr</replaceable> |
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
GENERATED ALWAYS AS ( <replaceable>generation_expr</replaceable> ) STORED |
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ] |
Add UNIQUE null treatment option The SQL standard has been ambiguous about whether null values in unique constraints should be considered equal or not. Different implementations have different behaviors. In the SQL:202x draft, this has been formalized by making this implementation-defined and adding an option on unique constraint definitions UNIQUE [ NULLS [NOT] DISTINCT ] to choose a behavior explicitly. This patch adds this option to PostgreSQL. The default behavior remains UNIQUE NULLS DISTINCT. Making this happen in the btree code is pretty easy; most of the patch is just to carry the flag around to all the places that need it. The CREATE UNIQUE INDEX syntax extension is not from the standard, it's my own invention. I named all the internal flags, catalog columns, etc. in the negative ("nulls not distinct") so that the default PostgreSQL behavior is the default if the flag is false. Reviewed-by: Maxim Orlov <orlovmg@gmail.com> Reviewed-by: Pavel Borisov <pashkin.elfe@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/84e5ee1b-387e-9a54-c326-9082674bde78@enterprisedb.com
2022-02-03 11:29:54 +01:00
UNIQUE [ NULLS [ NOT ] DISTINCT ] <replaceable class="parameter">index_parameters</replaceable> |
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
PRIMARY KEY <replaceable class="parameter">index_parameters</replaceable> |
REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
Clarify referential actions in docs of CREATE/ALTER TABLE The documentation of ON DELETE and ON UPDATE uses the term "action", which is also used on the ALTER TABLE page for other purposes. This commit renames the term to "referential_action", which is more consistent with the SQL specification. The new term is now used on the documentation of both CREATE TABLE and ALTER TABLE for consistency. Reported-by: Brigitte Blanc-Lafay Author: Lætitia Avrot Reviewed-by: Álvaro Herrera Discussion: https://postgr.es/m/CAB_COdiHEVVs0uB+uYCjjYUwQ4YFFekppq+Xqv6qAM8+cd42gA@mail.gmail.com
2018-12-28 02:19:14 +01:00
[ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ] }
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase>and <replaceable class="parameter">table_constraint</replaceable> is:</phrase>
Bring CREATE TABLE syntax synopsis into line with reality; update a bunch of old or poorly-worded documentation.
2001-01-12 06:06:40 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
{ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] |
Catalog not-null constraints We now create contype='n' pg_constraint rows for not-null constraints. We propagate these constraints to other tables during operations such as adding inheritance relationships, creating and attaching partitions and creating tables LIKE other tables. We also spawn not-null constraints for inheritance child tables when their parents have primary keys. These related constraints mostly follow the well-known rules of conislocal and coninhcount that we have for CHECK constraints, with some adaptations: for example, as opposed to CHECK constraints, we don't match not-null ones by name when descending a hierarchy to alter it, instead matching by column name that they apply to. This means we don't require the constraint names to be identical across a hierarchy. For now, we omit them for system catalogs. Maybe this is worth reconsidering. We don't support NOT VALID nor DEFERRABLE clauses either; these can be added as separate features later (this patch is already large and complicated enough.) psql shows these constraints in \d+. pg_dump requires some ad-hoc hacks, particularly when dumping a primary key. We now create one "throwaway" not-null constraint for each column in the PK together with the CREATE TABLE command, and once the PK is created, all those throwaway constraints are removed. This avoids having to check each tuple for nullness when the dump restores the primary key creation. pg_upgrading from an older release requires a somewhat brittle procedure to create a constraint state that matches what would be created if the database were being created fresh in Postgres 17. I have tested all the scenarios I could think of, and it works correctly as far as I can tell, but I could have neglected weird cases. This patch has been very long in the making. The first patch was written by Bernd Helmle in 2010 to add a new pg_constraint.contype value ('n'), which I (Álvaro) then hijacked in 2011 and 2012, until that one was killed by the realization that we ought to use contype='c' instead: manufactured CHECK constraints. However, later SQL standard development, as well as nonobvious emergent properties of that design (mostly, failure to distinguish them from "normal" CHECK constraints as well as the performance implication of having to test the CHECK expression) led us to reconsider this choice, so now the current implementation uses contype='n' again. During Postgres 16 this had already been introduced by commit e056c557aef4, but there were some problems mainly with the pg_upgrade procedure that couldn't be fixed in reasonable time, so it was reverted. In 2016 Vitaly Burovoy also worked on this feature[1] but found no consensus for his proposed approach, which was claimed to be closer to the letter of the standard, requiring an additional pg_attribute column to track the OID of the not-null constraint for that column. [1] https://postgr.es/m/CAKOSWNkN6HSyatuys8xZxzRCR-KL1OkHS5-b9qd9bf1Rad3PLA@mail.gmail.com Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Author: Bernd Helmle <mailings@oopsware.de> Reviewed-by: Justin Pryzby <pryzby@telsasoft.com> Reviewed-by: Peter Eisentraut <peter.eisentraut@enterprisedb.com> Reviewed-by: Dean Rasheed <dean.a.rasheed@gmail.com>
2023-08-25 13:31:24 +02:00
NOT NULL <replaceable class="parameter">column_name</replaceable> [ NO INHERIT ] |
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) <replaceable class="parameter">index_parameters</replaceable> |
PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] ) <replaceable class="parameter">index_parameters</replaceable> |
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ] |
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
FOREIGN KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] ) REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] ) ]
Clarify referential actions in docs of CREATE/ALTER TABLE The documentation of ON DELETE and ON UPDATE uses the term "action", which is also used on the ALTER TABLE page for other purposes. This commit renames the term to "referential_action", which is more consistent with the SQL specification. The new term is now used on the documentation of both CREATE TABLE and ALTER TABLE for consistency. Reported-by: Brigitte Blanc-Lafay Author: Lætitia Avrot Reviewed-by: Álvaro Herrera Discussion: https://postgr.es/m/CAB_COdiHEVVs0uB+uYCjjYUwQ4YFFekppq+Xqv6qAM8+cd42gA@mail.gmail.com
2018-12-28 02:19:14 +01:00
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <replaceable
class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ] }
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase>and <replaceable class="parameter">like_option</replaceable> is:</phrase>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
doc: Add missing COMPRESSION into CREATE TABLE synopsis. Commit bbe0a81db6 introduced "INCLUDING COMPRESSION" option in CREATE TABLE command, but forgot to mention it in the CREATE TABLE syntax synopsis. Author: Fujii Masao Reviewed-by: Michael Paquier Discussion: https://postgr.es/m/54d30e66-dbd6-5485-aaf6-a291ed55919d@oss.nttdata.com
2021-04-15 16:15:19 +02:00
{ INCLUDING | EXCLUDING } { COMMENTS | COMPRESSION | CONSTRAINTS | DEFAULTS | GENERATED | IDENTITY | INDEXES | STATISTICS | STORAGE | ALL }
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase>and <replaceable class="parameter">partition_bound_spec</replaceable> is:</phrase>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
Allow generalized expression syntax for partition bounds Previously, only literals were allowed. This change allows general expressions, including functions calls, which are evaluated at the time the DDL command is executed. Besides offering some more functionality, it simplifies the parser structures and removes some inconsistencies in how the literals were handled. Author: Kyotaro Horiguchi, Tom Lane, Amit Langote Reviewed-by: Peter Eisentraut <peter.eisentraut@2ndquadrant.com> Discussion: https://www.postgresql.org/message-id/flat/9f88b5e0-6da2-5227-20d0-0d7012beaa1c@lab.ntt.co.jp/
2019-01-25 11:27:59 +01:00
IN ( <replaceable class="parameter">partition_bound_expr</replaceable> [, ...] ) |
FROM ( { <replaceable class="parameter">partition_bound_expr</replaceable> | MINVALUE | MAXVALUE } [, ...] )
TO ( { <replaceable class="parameter">partition_bound_expr</replaceable> | MINVALUE | MAXVALUE } [, ...] ) |
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REMAINDER <replaceable class="parameter">numeric_literal</replaceable> )
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase><replaceable class="parameter">index_parameters</replaceable> in <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal> constraints are:</phrase>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Improve docs for the new INCLUDE directive in CREATE/ALTER TABLE. Author: Michael Paquier Discussion: https://www.postgresql.org/message-id/20180411082020.GD19732%40paquier.xyz
2018-04-18 11:44:29 +02:00
[ INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
[ USING INDEX TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase><replaceable class="parameter">exclude_element</replaceable> in an <literal>EXCLUDE</literal> constraint is:</phrase>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Make placeholders in SQL command help more consistent and precise To avoid divergent names on related pages, avoid ambiguities, and reduce translation work a little.
2012-06-22 00:06:14 +02:00
{ <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
doc: Add referential actions to CREATE/ALTER TABLE synopsis The general constraint synopsis references "referential_action", but this was not further defined in the synopsis section. Compared to the level of detail that the synopsis gives to other subclauses, this should surely be there. extracted from a patch by Paul Martinez <hellopfm@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-11-11 10:49:44 +01:00
<phrase><replaceable class="parameter">referential_action</replaceable> in a <literal>FOREIGN KEY</literal>/<literal>REFERENCES</literal> constraint is:</phrase>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
{ NO ACTION | RESTRICT | CASCADE | SET NULL [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] | SET DEFAULT [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] }
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</synopsis>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</refsynopsisdiv>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refsect1 id="sql-createtable-description">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<title>Description</title>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<command>CREATE TABLE</command> will create a new, initially empty table
in the current database. The table will be owned by the user issuing the
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
command.
Clean up to ensure tag completion as required by the newest versions of Norm's Modular Style Sheets and jade/docbook. From Vince Vielhaber <vev@michvhf.com>.
1998-12-29 03:24:47 +01:00
</para>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<para>
If a schema name is given (for example, <literal>CREATE TABLE
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
myschema.mytable ...</literal>) then the table is created in the specified
Add support for temporary views, including documentation and regression tests. Contributed by Koju Iijima, review from Neil Conway, Gavin Sherry and Tom Lane. Also, fix error in description of WITH CHECK OPTION clause in the CREATE VIEW reference page: it should be "CASCADED", not "CASCADE".
2005-02-02 07:36:02 +01:00
schema. Otherwise it is created in the current schema. Temporary
Update reference 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".
2007-02-01 00:26:05 +01:00
tables exist in a special schema, so a schema name cannot be given
Add support for temporary views, including documentation and regression tests. Contributed by Koju Iijima, review from Neil Conway, Gavin Sherry and Tom Lane. Also, fix error in description of WITH CHECK OPTION clause in the CREATE VIEW reference page: it should be "CASCADED", not "CASCADE".
2005-02-02 07:36:02 +01:00
when creating a temporary table. The name of the table must be
Doc: be more precise about conflicts between relation names. Use verbiage like "The name of the table must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema." in the reference pages for all those object types. The main change here is to mention materialized views explicitly; although a couple of these pages failed to say anything at all about name conflicts. Per suggestion from Daniel Westermann. Discussion: https://postgr.es/m/ZR0P278MB0920D0946509233459AF0DEFD2889@ZR0P278MB0920.CHEP278.PROD.OUTLOOK.COM
2021-11-02 17:12:02 +01:00
distinct from the name of any other relation (table, sequence, index, view,
materialized view, or foreign table) in the same schema.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<command>CREATE TABLE</command> also automatically creates a data
More editing of reference pages.
2003-04-22 12:08:08 +02:00
type that represents the composite type corresponding
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
to one row of the table. Therefore, tables cannot have the same
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
name as any existing data type in the same schema.
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
</para>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
The optional constraint clauses specify constraints (tests) that
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
new or updated rows must satisfy for an insert or update operation
More editing of reference pages.
2003-04-22 12:08:08 +02:00
to succeed. A constraint is an SQL object that helps define the
set of valid values in the table in various ways.
Bring CREATE TABLE syntax synopsis into line with reality; update a bunch of old or poorly-worded documentation.
2001-01-12 06:06:40 +01:00
</para>
Describe handling of multiply-inherited fields correctly.
2001-05-03 19:50:55 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
There are two ways to define constraints: table constraints and
column constraints. A column constraint is defined as part of a
column definition. A table constraint definition is not tied to a
particular column, and it can encompass more than one column.
Every column constraint can also be written as a table constraint;
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
a column constraint is only a notational convenience for use when the
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
constraint only affects one column.
Describe handling of multiply-inherited fields correctly.
2001-05-03 19:50:55 +02:00
</para>
Add support for privileges on types This adds support for the more or less SQL-conforming USAGE privilege on types and domains. The intent is to be able restrict which users can create dependencies on types, which restricts the way in which owners can alter types. reviewed by Yeb Havinga
2011-12-19 23:05:19 +01:00
<para>
To be able to create a table, you must have <literal>USAGE</literal>
privilege on all column types or the type in the <literal>OF</literal>
clause, respectively.
</para>
Describe handling of multiply-inherited fields correctly.
2001-05-03 19:50:55 +02:00
</refsect1>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<refsect1>
<title>Parameters</title>
Describe handling of multiply-inherited fields correctly.
2001-05-03 19:50:55 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<variablelist>
Describe handling of multiply-inherited fields correctly.
2001-05-03 19:50:55 +02:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<varlistentry id="sql-createtable-temporary">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
If specified, the table is created as a temporary table.
Temporary tables are automatically dropped at the end of a
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
session, or optionally at the end of the current transaction
Clarify temporary table name shadowing in CREATE TABLE docs Author: David Johnston
2020-11-02 15:00:24 +01:00
(see <literal>ON COMMIT</literal> below). The default
search_path includes the temporary schema first and so identically
named existing permanent tables are not chosen for new plans
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
while the temporary table exists, unless they are referenced
with schema-qualified names. Any indexes created on a temporary
table are automatically temporary as well.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Document that autovacuum cannot vacuum or analyze temporary tables.
2010-04-16 04:22:33 +02:00
<para>
The <link linkend="autovacuum">autovacuum daemon</link> cannot
access and therefore cannot vacuum or analyze temporary tables.
For this reason, appropriate vacuum and analyze operations should be
performed via session SQL commands. For example, if a temporary
table is going to be used in complex queries, it is wise to run
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<command>ANALYZE</command> on the temporary table after it is populated.
Document that autovacuum cannot vacuum or analyze temporary tables.
2010-04-16 04:22:33 +02:00
</para>
Use "TOAST table" in place of the vague, not-used-elsewhere phrase "supplementary storage table".
2010-05-13 20:54:18 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
When a TIMESTAMP, TIME, or INTERVAL precision is specified larger than our implementation limits, do not issue an ERROR; instead issue a NOTICE and use the max supported value. Per pgsql-general discussion of 28-Apr, this is needed to allow easy porting from pre-7.3 releases where the limits were higher. Unrelated change in same area: accept GLOBAL TEMP/TEMPORARY as a synonym for TEMPORARY, as per pgsql-hackers discussion of 15-Apr. We previously rejected it, but that was based on a misreading of the spec --- SQL92's GLOBAL temp tables are really closer to what we have than their LOCAL ones.
2003-05-04 02:03:55 +02:00
Optionally, <literal>GLOBAL</literal> or <literal>LOCAL</literal>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>.
This presently makes no difference in <productname>PostgreSQL</productname>
Deprecate use of GLOBAL and LOCAL in temp table creation. Aside from adjusting the documentation to say that these are deprecated, we now report a warning (not an error) for use of GLOBAL, since it seems fairly likely that we might change that to request SQL-spec-compliant temp table behavior in the foreseeable future. Although our handling of LOCAL is equally nonstandard, there is no evident interest in ever implementing SQL modules, and furthermore some other products interpret LOCAL as behaving the same way we do. So no expectation of change and no warning for LOCAL; but it still seems a good idea to deprecate writing it. Noah Misch
2012-06-13 23:48:42 +02:00
and is deprecated; see
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs. Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
2020-05-11 20:15:49 +02:00
<xref linkend="sql-createtable-compatibility"/> below.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Clean up to ensure tag completion as required by the newest versions of Norm's Modular Style Sheets and jade/docbook. From Vince Vielhaber <vev@michvhf.com>.
1998-12-29 03:24:47 +01:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<varlistentry id="sql-createtable-unlogged">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>UNLOGGED</literal></term>
Support unlogged tables. The contents of an unlogged table are WAL-logged; thus, they are not available on standby servers and are truncated whenever the database system enters recovery. Indexes on unlogged tables are also unlogged. Unlogged GiST indexes are not currently supported.
2010-12-29 12:48:53 +01:00
<listitem>
<para>
If specified, the table is created as an unlogged table. Data written
to unlogged tables is not written to the write-ahead log (see <xref
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
linkend="wal"/>), which makes them considerably faster than ordinary
Support unlogged tables. The contents of an unlogged table are WAL-logged; thus, they are not available on standby servers and are truncated whenever the database system enters recovery. Indexes on unlogged tables are also unlogged. Unlogged GiST indexes are not currently supported.
2010-12-29 12:48:53 +01:00
tables. However, they are not crash-safe: an unlogged table is
automatically truncated after a crash or unclean shutdown. The contents
of an unlogged table are also not replicated to standby servers.
Any indexes created on an unlogged table are automatically unlogged as
Support unlogged GiST index. The reason this wasn't supported before was that GiST indexes need an increasing sequence to detect concurrent page-splits. In a regular WAL- logged GiST index, the LSN of the page-split record is used for that purpose, and in a temporary index, we can get away with a backend-local counter. Neither of those methods works for an unlogged relation. To provide such an increasing sequence of numbers, create a "fake LSN" counter that is saved and restored across shutdowns. On recovery, unlogged relations are blown away, so the counter doesn't need to survive that either. Jeevan Chalke, based on discussions with Robert Haas, Tom Lane and me.
2013-02-11 21:50:15 +01:00
well.
Support unlogged tables. The contents of an unlogged table are WAL-logged; thus, they are not available on standby servers and are truncated whenever the database system enters recovery. Indexes on unlogged tables are also unlogged. Unlogged GiST indexes are not currently supported.
2010-12-29 12:48:53 +01:00
</para>
Unlogged sequences Add support for unlogged sequences. Unlike for unlogged tables, this is not a performance feature. It allows sequences associated with unlogged tables to be excluded from replication. A new subcommand ALTER SEQUENCE ... SET LOGGED/UNLOGGED is added. An identity/serial sequence now automatically gets and follows the persistence level (logged/unlogged) of its owning table. (The sequences owned by temporary tables were already temporary through the separate mechanism in RangeVarAdjustRelationPersistence().) But you can still change the persistence of an owned sequence separately. Also, pg_dump and pg_upgrade preserve the persistence of existing sequences. Discussion: https://www.postgresql.org/message-id/flat/04e12818-2f98-257c-b926-2845d74ed04f%402ndquadrant.com
2022-04-07 16:13:23 +02:00
<para>
If this is specified, any sequences created together with the unlogged
table (for identity or serial columns) are also created as unlogged.
</para>
Support unlogged tables. The contents of an unlogged table are WAL-logged; thus, they are not available on standby servers and are truncated whenever the database system enters recovery. Indexes on unlogged tables are also unlogged. Unlogged GiST indexes are not currently supported.
2010-12-29 12:48:53 +01:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-if-not-exists">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>IF NOT EXISTS</literal></term>
CREATE TABLE IF NOT EXISTS. Reviewed by Bernd Helmle.
2010-07-26 01:21:22 +02:00
<listitem>
<para>
Do not throw an error if a relation with the same name already exists.
Remove tabs from sgml file.
2010-07-26 03:43:52 +02:00
A notice is issued in this case. Note that there is no guarantee that
the existing relation is anything like the one that would have been
created.
CREATE TABLE IF NOT EXISTS. Reviewed by Bernd Helmle.
2010-07-26 01:21:22 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-table-name">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">table_name</replaceable></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
The name (optionally schema-qualified) of the table to be created.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Editing and markup cleanup.
1998-09-22 17:48:03 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-type-name">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>OF <replaceable class="parameter">type_name</replaceable></literal></term>
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
<listitem>
<para>
Creates a <firstterm>typed table</firstterm>, which takes its
structure from the specified composite type (name optionally
schema-qualified). A typed table is tied to its type; for
example the table will be dropped if the type is dropped
(with <literal>DROP TYPE ... CASCADE</literal>).
</para>
<para>
When a typed table is created, then the data types of the
columns are determined by the underlying composite type and are
not specified by the <literal>CREATE TABLE</literal> command.
But the <literal>CREATE TABLE</literal> command can add defaults
and constraints to the table and can specify storage parameters.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-column-name">
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
<term><replaceable class="parameter">column_name</replaceable></term>
<listitem>
<para>
The name of a column to be created in the new table.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-data-type">
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
<term><replaceable class="parameter">data_type</replaceable></term>
<listitem>
<para>
The data type of the column. This can include array
specifiers. For more information on the data types supported by
<productname>PostgreSQL</productname>, refer to <xref
linkend="datatype"/>.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-collate">
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
<term><literal>COLLATE <replaceable>collation</replaceable></literal></term>
<listitem>
<para>
The <literal>COLLATE</literal> clause assigns a collation to
the column (which must be of a collatable data type).
If not specified, the column data type's default collation is used.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-storage">
Allow specifying STORAGE attribute for a new table Previously, the STORAGE specification was only available in ALTER TABLE. This makes it available in CREATE TABLE as well. Also make the code and the documentation for STORAGE and COMPRESSION attributes consistent. Author: Teodor Sigaev <teodor@sigaev.ru> Author: Aleksander Alekseev <aleksander@timescale.com> Reviewed-by: Peter Eisentraut <peter.eisentraut@enterprisedb.com> Reviewed-by: wenjing zeng <wjzeng2012@gmail.com> Reviewed-by: Matthias van de Meent <boekewurm+postgres@gmail.com> Reviewed-by: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Discussion: https://postgr.es/m/de83407a-ae3d-a8e1-a788-920eb334f25b@sigaev.ru
2022-07-13 12:21:45 +02:00
<term>
Support writing "CREATE/ALTER TABLE ... SET STORAGE DEFAULT". We already allow explicitly writing DEFAULT for SET COMPRESSION, so it seems a bit inflexible and non-orthogonal to not have it for STORAGE. Aleksander Alekseev Discussion: https://postgr.es/m/CAJ7c6TMX9ui+6y3TQFaXJYVpZyBukvqhQbVDJ8OUokeLRhtnpA@mail.gmail.com
2022-11-11 00:20:49 +01:00
<literal>STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }</literal>
Allow specifying STORAGE attribute for a new table Previously, the STORAGE specification was only available in ALTER TABLE. This makes it available in CREATE TABLE as well. Also make the code and the documentation for STORAGE and COMPRESSION attributes consistent. Author: Teodor Sigaev <teodor@sigaev.ru> Author: Aleksander Alekseev <aleksander@timescale.com> Reviewed-by: Peter Eisentraut <peter.eisentraut@enterprisedb.com> Reviewed-by: wenjing zeng <wjzeng2012@gmail.com> Reviewed-by: Matthias van de Meent <boekewurm+postgres@gmail.com> Reviewed-by: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Discussion: https://postgr.es/m/de83407a-ae3d-a8e1-a788-920eb334f25b@sigaev.ru
2022-07-13 12:21:45 +02:00
<indexterm>
<primary>TOAST</primary>
<secondary>per-column storage settings</secondary>
</indexterm>
</term>
<listitem>
<para>
This form sets the storage mode for the column. This controls whether this
column is held inline or in a secondary <acronym>TOAST</acronym> table,
and whether the data should be compressed or not. <literal>PLAIN</literal>
must be used for fixed-length values such as <type>integer</type> and is
inline, uncompressed. <literal>MAIN</literal> is for inline, compressible
data. <literal>EXTERNAL</literal> is for external, uncompressed data, and
<literal>EXTENDED</literal> is for external, compressed data.
Support writing "CREATE/ALTER TABLE ... SET STORAGE DEFAULT". We already allow explicitly writing DEFAULT for SET COMPRESSION, so it seems a bit inflexible and non-orthogonal to not have it for STORAGE. Aleksander Alekseev Discussion: https://postgr.es/m/CAJ7c6TMX9ui+6y3TQFaXJYVpZyBukvqhQbVDJ8OUokeLRhtnpA@mail.gmail.com
2022-11-11 00:20:49 +01:00
Writing <literal>DEFAULT</literal> sets the storage mode to the default
mode for the column's data type. <literal>EXTENDED</literal> is the
default for most data types that support non-<literal>PLAIN</literal>
storage.
Use of <literal>EXTERNAL</literal> will make substring operations on
very large <type>text</type> and <type>bytea</type> values run faster,
at the penalty of increased storage space.
See <xref linkend="storage-toast"/> for more information.
Allow specifying STORAGE attribute for a new table Previously, the STORAGE specification was only available in ALTER TABLE. This makes it available in CREATE TABLE as well. Also make the code and the documentation for STORAGE and COMPRESSION attributes consistent. Author: Teodor Sigaev <teodor@sigaev.ru> Author: Aleksander Alekseev <aleksander@timescale.com> Reviewed-by: Peter Eisentraut <peter.eisentraut@enterprisedb.com> Reviewed-by: wenjing zeng <wjzeng2012@gmail.com> Reviewed-by: Matthias van de Meent <boekewurm+postgres@gmail.com> Reviewed-by: Kyotaro Horiguchi <horikyota.ntt@gmail.com> Discussion: https://postgr.es/m/de83407a-ae3d-a8e1-a788-920eb334f25b@sigaev.ru
2022-07-13 12:21:45 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-compression">
Allow configurable LZ4 TOAST compression. There is now a per-column COMPRESSION option which can be set to pglz (the default, and the only option in up until now) or lz4. Or, if you like, you can set the new default_toast_compression GUC to lz4, and then that will be the default for new table columns for which no value is specified. We don't have lz4 support in the PostgreSQL code, so to use lz4 compression, PostgreSQL must be built --with-lz4. In general, TOAST compression means compression of individual column values, not the whole tuple, and those values can either be compressed inline within the tuple or compressed and then stored externally in the TOAST table, so those properties also apply to this feature. Prior to this commit, a TOAST pointer has two unused bits as part of the va_extsize field, and a compessed datum has two unused bits as part of the va_rawsize field. These bits are unused because the length of a varlena is limited to 1GB; we now use them to indicate the compression type that was used. This means we only have bit space for 2 more built-in compresison types, but we could work around that problem, if necessary, by introducing a new vartag_external value for any further types we end up wanting to add. Hopefully, it won't be too important to offer a wide selection of algorithms here, since each one we add not only takes more coding but also adds a build dependency for every packager. Nevertheless, it seems worth doing at least this much, because LZ4 gets better compression than PGLZ with less CPU usage. It's possible for LZ4-compressed datums to leak into composite type values stored on disk, just as it is for PGLZ. It's also possible for LZ4-compressed attributes to be copied into a different table via SQL commands such as CREATE TABLE AS or INSERT .. SELECT. It would be expensive to force such values to be decompressed, so PostgreSQL has never done so. For the same reasons, we also don't force recompression of already-compressed values even if the target table prefers a different compression method than was used for the source data. These architectural decisions are perhaps arguable but revisiting them is well beyond the scope of what seemed possible to do as part of this project. However, it's relatively cheap to recompress as part of VACUUM FULL or CLUSTER, so this commit adjusts those commands to do so, if the configured compression method of the table happens not to match what was used for some column value stored therein. Dilip Kumar. The original patches on which this work was based were written by Ildus Kurbangaliev, and those were patches were based on even earlier work by Nikita Glukhov, but the design has since changed very substantially, since allow a potentially large number of compression methods that could be added and dropped on a running system proved too problematic given some of the architectural issues mentioned above; the choice of which specific compression method to add first is now different; and a lot of the code has been heavily refactored. More recently, Justin Przyby helped quite a bit with testing and reviewing and this version also includes some code contributions from him. Other design input and review from Tomas Vondra, Álvaro Herrera, Andres Freund, Oleg Bartunov, Alexander Korotkov, and me. Discussion: http://postgr.es/m/20170907194236.4cefce96%40wp.localdomain Discussion: http://postgr.es/m/CAFiTN-uUpX3ck%3DK0mLEk-G_kUQY%3DSNOTeqdaNRR9FMdQrHKebw%40mail.gmail.com
2021-03-19 20:10:38 +01:00
<term><literal>COMPRESSION <replaceable class="parameter">compression_method</replaceable></literal></term>
<listitem>
<para>
The <literal>COMPRESSION</literal> clause sets the compression method
Rethink definition of pg_attribute.attcompression. Redefine '\0' (InvalidCompressionMethod) as meaning "if we need to compress, use the current setting of default_toast_compression". This allows '\0' to be a suitable default choice regardless of datatype, greatly simplifying code paths that initialize tupledescs and the like. It seems like a more user-friendly approach as well, because now the default compression choice doesn't migrate into table definitions, meaning that changing default_toast_compression is usually sufficient to flip an installation's behavior; one needn't tediously issue per-column ALTER SET COMPRESSION commands. Along the way, fix a few minor bugs and documentation issues with the per-column-compression feature. Adopt more robust APIs for SetIndexStorageProperties and GetAttributeCompression. Bump catversion because typical contents of attcompression will now be different. We could get away without doing that, but it seems better to ensure v14 installations all agree on this. (We already forced initdb for beta2, anyway.) Discussion: https://postgr.es/m/626613.1621787110@sss.pgh.pa.us
2021-05-27 19:24:24 +02:00
for the column. Compression is supported only for variable-width data
types, and is used only when the column's storage mode
is <literal>main</literal> or <literal>extended</literal>.
(See <xref linkend="sql-altertable"/> for information on
column storage modes.) Setting this property for a partitioned table
Allow configurable LZ4 TOAST compression. There is now a per-column COMPRESSION option which can be set to pglz (the default, and the only option in up until now) or lz4. Or, if you like, you can set the new default_toast_compression GUC to lz4, and then that will be the default for new table columns for which no value is specified. We don't have lz4 support in the PostgreSQL code, so to use lz4 compression, PostgreSQL must be built --with-lz4. In general, TOAST compression means compression of individual column values, not the whole tuple, and those values can either be compressed inline within the tuple or compressed and then stored externally in the TOAST table, so those properties also apply to this feature. Prior to this commit, a TOAST pointer has two unused bits as part of the va_extsize field, and a compessed datum has two unused bits as part of the va_rawsize field. These bits are unused because the length of a varlena is limited to 1GB; we now use them to indicate the compression type that was used. This means we only have bit space for 2 more built-in compresison types, but we could work around that problem, if necessary, by introducing a new vartag_external value for any further types we end up wanting to add. Hopefully, it won't be too important to offer a wide selection of algorithms here, since each one we add not only takes more coding but also adds a build dependency for every packager. Nevertheless, it seems worth doing at least this much, because LZ4 gets better compression than PGLZ with less CPU usage. It's possible for LZ4-compressed datums to leak into composite type values stored on disk, just as it is for PGLZ. It's also possible for LZ4-compressed attributes to be copied into a different table via SQL commands such as CREATE TABLE AS or INSERT .. SELECT. It would be expensive to force such values to be decompressed, so PostgreSQL has never done so. For the same reasons, we also don't force recompression of already-compressed values even if the target table prefers a different compression method than was used for the source data. These architectural decisions are perhaps arguable but revisiting them is well beyond the scope of what seemed possible to do as part of this project. However, it's relatively cheap to recompress as part of VACUUM FULL or CLUSTER, so this commit adjusts those commands to do so, if the configured compression method of the table happens not to match what was used for some column value stored therein. Dilip Kumar. The original patches on which this work was based were written by Ildus Kurbangaliev, and those were patches were based on even earlier work by Nikita Glukhov, but the design has since changed very substantially, since allow a potentially large number of compression methods that could be added and dropped on a running system proved too problematic given some of the architectural issues mentioned above; the choice of which specific compression method to add first is now different; and a lot of the code has been heavily refactored. More recently, Justin Przyby helped quite a bit with testing and reviewing and this version also includes some code contributions from him. Other design input and review from Tomas Vondra, Álvaro Herrera, Andres Freund, Oleg Bartunov, Alexander Korotkov, and me. Discussion: http://postgr.es/m/20170907194236.4cefce96%40wp.localdomain Discussion: http://postgr.es/m/CAFiTN-uUpX3ck%3DK0mLEk-G_kUQY%3DSNOTeqdaNRR9FMdQrHKebw%40mail.gmail.com
2021-03-19 20:10:38 +01:00
has no direct effect, because such tables have no storage of their own,
Rethink definition of pg_attribute.attcompression. Redefine '\0' (InvalidCompressionMethod) as meaning "if we need to compress, use the current setting of default_toast_compression". This allows '\0' to be a suitable default choice regardless of datatype, greatly simplifying code paths that initialize tupledescs and the like. It seems like a more user-friendly approach as well, because now the default compression choice doesn't migrate into table definitions, meaning that changing default_toast_compression is usually sufficient to flip an installation's behavior; one needn't tediously issue per-column ALTER SET COMPRESSION commands. Along the way, fix a few minor bugs and documentation issues with the per-column-compression feature. Adopt more robust APIs for SetIndexStorageProperties and GetAttributeCompression. Bump catversion because typical contents of attcompression will now be different. We could get away without doing that, but it seems better to ensure v14 installations all agree on this. (We already forced initdb for beta2, anyway.) Discussion: https://postgr.es/m/626613.1621787110@sss.pgh.pa.us
2021-05-27 19:24:24 +02:00
but the configured value will be inherited by newly-created partitions.
Allow configurable LZ4 TOAST compression. There is now a per-column COMPRESSION option which can be set to pglz (the default, and the only option in up until now) or lz4. Or, if you like, you can set the new default_toast_compression GUC to lz4, and then that will be the default for new table columns for which no value is specified. We don't have lz4 support in the PostgreSQL code, so to use lz4 compression, PostgreSQL must be built --with-lz4. In general, TOAST compression means compression of individual column values, not the whole tuple, and those values can either be compressed inline within the tuple or compressed and then stored externally in the TOAST table, so those properties also apply to this feature. Prior to this commit, a TOAST pointer has two unused bits as part of the va_extsize field, and a compessed datum has two unused bits as part of the va_rawsize field. These bits are unused because the length of a varlena is limited to 1GB; we now use them to indicate the compression type that was used. This means we only have bit space for 2 more built-in compresison types, but we could work around that problem, if necessary, by introducing a new vartag_external value for any further types we end up wanting to add. Hopefully, it won't be too important to offer a wide selection of algorithms here, since each one we add not only takes more coding but also adds a build dependency for every packager. Nevertheless, it seems worth doing at least this much, because LZ4 gets better compression than PGLZ with less CPU usage. It's possible for LZ4-compressed datums to leak into composite type values stored on disk, just as it is for PGLZ. It's also possible for LZ4-compressed attributes to be copied into a different table via SQL commands such as CREATE TABLE AS or INSERT .. SELECT. It would be expensive to force such values to be decompressed, so PostgreSQL has never done so. For the same reasons, we also don't force recompression of already-compressed values even if the target table prefers a different compression method than was used for the source data. These architectural decisions are perhaps arguable but revisiting them is well beyond the scope of what seemed possible to do as part of this project. However, it's relatively cheap to recompress as part of VACUUM FULL or CLUSTER, so this commit adjusts those commands to do so, if the configured compression method of the table happens not to match what was used for some column value stored therein. Dilip Kumar. The original patches on which this work was based were written by Ildus Kurbangaliev, and those were patches were based on even earlier work by Nikita Glukhov, but the design has since changed very substantially, since allow a potentially large number of compression methods that could be added and dropped on a running system proved too problematic given some of the architectural issues mentioned above; the choice of which specific compression method to add first is now different; and a lot of the code has been heavily refactored. More recently, Justin Przyby helped quite a bit with testing and reviewing and this version also includes some code contributions from him. Other design input and review from Tomas Vondra, Álvaro Herrera, Andres Freund, Oleg Bartunov, Alexander Korotkov, and me. Discussion: http://postgr.es/m/20170907194236.4cefce96%40wp.localdomain Discussion: http://postgr.es/m/CAFiTN-uUpX3ck%3DK0mLEk-G_kUQY%3DSNOTeqdaNRR9FMdQrHKebw%40mail.gmail.com
2021-03-19 20:10:38 +01:00
The supported compression methods are <literal>pglz</literal> and
Rethink definition of pg_attribute.attcompression. Redefine '\0' (InvalidCompressionMethod) as meaning "if we need to compress, use the current setting of default_toast_compression". This allows '\0' to be a suitable default choice regardless of datatype, greatly simplifying code paths that initialize tupledescs and the like. It seems like a more user-friendly approach as well, because now the default compression choice doesn't migrate into table definitions, meaning that changing default_toast_compression is usually sufficient to flip an installation's behavior; one needn't tediously issue per-column ALTER SET COMPRESSION commands. Along the way, fix a few minor bugs and documentation issues with the per-column-compression feature. Adopt more robust APIs for SetIndexStorageProperties and GetAttributeCompression. Bump catversion because typical contents of attcompression will now be different. We could get away without doing that, but it seems better to ensure v14 installations all agree on this. (We already forced initdb for beta2, anyway.) Discussion: https://postgr.es/m/626613.1621787110@sss.pgh.pa.us
2021-05-27 19:24:24 +02:00
<literal>lz4</literal>. (<literal>lz4</literal> is available only if
<option>--with-lz4</option> was used when building
<productname>PostgreSQL</productname>.) In addition,
<replaceable class="parameter">compression_method</replaceable>
can be <literal>default</literal> to explicitly specify the default
behavior, which is to consult the
<xref linkend="guc-default-toast-compression"/> setting at the time of
data insertion to determine the method to use.
Allow configurable LZ4 TOAST compression. There is now a per-column COMPRESSION option which can be set to pglz (the default, and the only option in up until now) or lz4. Or, if you like, you can set the new default_toast_compression GUC to lz4, and then that will be the default for new table columns for which no value is specified. We don't have lz4 support in the PostgreSQL code, so to use lz4 compression, PostgreSQL must be built --with-lz4. In general, TOAST compression means compression of individual column values, not the whole tuple, and those values can either be compressed inline within the tuple or compressed and then stored externally in the TOAST table, so those properties also apply to this feature. Prior to this commit, a TOAST pointer has two unused bits as part of the va_extsize field, and a compessed datum has two unused bits as part of the va_rawsize field. These bits are unused because the length of a varlena is limited to 1GB; we now use them to indicate the compression type that was used. This means we only have bit space for 2 more built-in compresison types, but we could work around that problem, if necessary, by introducing a new vartag_external value for any further types we end up wanting to add. Hopefully, it won't be too important to offer a wide selection of algorithms here, since each one we add not only takes more coding but also adds a build dependency for every packager. Nevertheless, it seems worth doing at least this much, because LZ4 gets better compression than PGLZ with less CPU usage. It's possible for LZ4-compressed datums to leak into composite type values stored on disk, just as it is for PGLZ. It's also possible for LZ4-compressed attributes to be copied into a different table via SQL commands such as CREATE TABLE AS or INSERT .. SELECT. It would be expensive to force such values to be decompressed, so PostgreSQL has never done so. For the same reasons, we also don't force recompression of already-compressed values even if the target table prefers a different compression method than was used for the source data. These architectural decisions are perhaps arguable but revisiting them is well beyond the scope of what seemed possible to do as part of this project. However, it's relatively cheap to recompress as part of VACUUM FULL or CLUSTER, so this commit adjusts those commands to do so, if the configured compression method of the table happens not to match what was used for some column value stored therein. Dilip Kumar. The original patches on which this work was based were written by Ildus Kurbangaliev, and those were patches were based on even earlier work by Nikita Glukhov, but the design has since changed very substantially, since allow a potentially large number of compression methods that could be added and dropped on a running system proved too problematic given some of the architectural issues mentioned above; the choice of which specific compression method to add first is now different; and a lot of the code has been heavily refactored. More recently, Justin Przyby helped quite a bit with testing and reviewing and this version also includes some code contributions from him. Other design input and review from Tomas Vondra, Álvaro Herrera, Andres Freund, Oleg Bartunov, Alexander Korotkov, and me. Discussion: http://postgr.es/m/20170907194236.4cefce96%40wp.localdomain Discussion: http://postgr.es/m/CAFiTN-uUpX3ck%3DK0mLEk-G_kUQY%3DSNOTeqdaNRR9FMdQrHKebw%40mail.gmail.com
2021-03-19 20:10:38 +01:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-inherits">
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
<term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term>
<listitem>
<para>
The optional <literal>INHERITS</literal> clause specifies a list of
tables from which the new table automatically inherits all
columns. Parent tables can be plain tables or foreign tables.
</para>
<para>
Use of <literal>INHERITS</literal> creates a persistent relationship
between the new child table and its parent table(s). Schema
modifications to the parent(s) normally propagate to children
as well, and by default the data of the child table is included in
scans of the parent(s).
</para>
<para>
If the same column name exists in more than one parent
table, an error is reported unless the data types of the columns
match in each of the parent tables. If there is no conflict,
then the duplicate columns are merged to form a single column in
the new table. If the column name list of the new table
contains a column name that is also inherited, the data type must
likewise match the inherited column(s), and the column
definitions are merged into one. If the
new table explicitly specifies a default value for the column,
this default overrides any defaults from inherited declarations
of the column. Otherwise, any parents that specify default
values for the column must all specify the same default, or an
error will be reported.
</para>
<para>
<literal>CHECK</literal> constraints are merged in essentially the same way as
columns: if multiple parent tables and/or the new table definition
contain identically-named <literal>CHECK</literal> constraints, these
constraints must all have the same check expression, or an error will be
reported. Constraints having the same name and expression will
be merged into one copy. A constraint marked <literal>NO INHERIT</literal> in a
parent will not be considered. Notice that an unnamed <literal>CHECK</literal>
constraint in the new table will never be merged, since a unique name
will always be chosen for it.
</para>
<para>
Revert "Improve compression and storage support with inheritance" This reverts commit 0413a556990ba628a3de8a0b58be020fd9a14ed0. pg_dump cannot currently dump all the structures that are allowed by this patch. This needs more work in pg_dump and more test coverage. Discussion: https://www.postgresql.org/message-id/flat/24656cec-d6ef-4d15-8b5b-e8dfc9c833a7@eisentraut.org
2024-02-20 11:10:59 +01:00
Column <literal>STORAGE</literal> settings are also copied from parent tables.
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
</para>
<para>
If a column in the parent table is an identity column, that property is
not inherited. A column in the child table can be declared identity
column if desired.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-partition-by">
doc: move PARTITION OF stanza to just below PARTITION BY It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-07-17 06:54:34 +02:00
<term><literal>PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] ) </literal></term>
<listitem>
<para>
The optional <literal>PARTITION BY</literal> clause specifies a strategy
of partitioning the table. The table thus created is called a
<firstterm>partitioned</firstterm> table. The parenthesized list of
columns or expressions forms the <firstterm>partition key</firstterm>
for the table. When using range or hash partitioning, the partition key
can include multiple columns or expressions (up to 32, but this limit can
be altered when building <productname>PostgreSQL</productname>), but for
list partitioning, the partition key must consist of a single column or
expression.
</para>
<para>
Range and list partitioning require a btree operator class, while hash
partitioning requires a hash operator class. If no operator class is
specified explicitly, the default operator class of the appropriate
type will be used; if no default operator class exists, an error will
be raised. When hash partitioning is used, the operator class used
must implement support function 2 (see <xref linkend="xindex-support"/>
for details).
</para>
<para>
A partitioned table is divided into sub-tables (called partitions),
which are created using separate <literal>CREATE TABLE</literal> commands.
The partitioned table is itself empty. A data row inserted into the
table is routed to a partition based on the value of columns or
expressions in the partition key. If no existing partition matches
the values in the new row, an error will be reported.
</para>
<para>
Partitioned tables do not support <literal>EXCLUDE</literal> constraints;
however, you can define these constraints on individual partitions.
</para>
<para>
See <xref linkend="ddl-partitioning"/> for more discussion on table
partitioning.
</para>
</listitem>
</varlistentry>
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<varlistentry id="sql-createtable-partition">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>PARTITION OF <replaceable class="parameter">parent_table</replaceable> { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }</literal></term>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<listitem>
<para>
Docs: improve CREATE TABLE ref page's discussion of partition bounds. Clarify in the syntax synopsis that partition bound values must be exactly numeric literals or string literals; previously it said "bound_literal" which was defined nowhere. Replace confusing --- and, I think, incorrect in detail --- definition of how range bounds work with a reference to row-wise comparison plus a concrete example (which I stole from Robert Haas). Minor copy-editing in the same area. Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
2017-06-07 23:23:38 +02:00
Creates the table as a <firstterm>partition</firstterm> of the specified
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
parent table. The table can be created either as a partition for specific
values using <literal>FOR VALUES</literal> or as a default partition
Document partitiong tables ancillary object handling some more Add a couple of lines to make it explicit that indexes, constraints, triggers are added, removed, or left alone. Backpatch to pg11. Author: Álvaro Herrera <alvherre@alvh.no-ip.org> Reviewed-by: Justin Pryzby <pryzby@telsasoft.com> Discussion: https://postgr.es/m/20200421162038.GA18628@alvherre.pgsql
2020-04-21 23:14:18 +02:00
using <literal>DEFAULT</literal>. Any indexes, constraints and
user-defined row-level triggers that exist in the parent table are cloned
on the new partition.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
<para>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
The <replaceable class="parameter">partition_bound_spec</replaceable>
Docs: improve CREATE TABLE ref page's discussion of partition bounds. Clarify in the syntax synopsis that partition bound values must be exactly numeric literals or string literals; previously it said "bound_literal" which was defined nowhere. Replace confusing --- and, I think, incorrect in detail --- definition of how range bounds work with a reference to row-wise comparison plus a concrete example (which I stole from Robert Haas). Minor copy-editing in the same area. Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
2017-06-07 23:23:38 +02:00
must correspond to the partitioning method and partition key of the
parent table, and must not overlap with any existing partition of that
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
parent. The form with <literal>IN</literal> is used for list partitioning,
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
the form with <literal>FROM</literal> and <literal>TO</literal> is used
for range partitioning, and the form with <literal>WITH</literal> is used
for hash partitioning.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
Tidy up the CREATE TABLE documentation for partitioning. Remove some <note> tags that make this too "loud". Fix some typos. Amit Langote, with a few minor corrections by me Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:00:09 +02:00
<para>
Allow generalized expression syntax for partition bounds Previously, only literals were allowed. This change allows general expressions, including functions calls, which are evaluated at the time the DDL command is executed. Besides offering some more functionality, it simplifies the parser structures and removes some inconsistencies in how the literals were handled. Author: Kyotaro Horiguchi, Tom Lane, Amit Langote Reviewed-by: Peter Eisentraut <peter.eisentraut@2ndquadrant.com> Discussion: https://www.postgresql.org/message-id/flat/9f88b5e0-6da2-5227-20d0-0d7012beaa1c@lab.ntt.co.jp/
2019-01-25 11:27:59 +01:00
<replaceable class="parameter">partition_bound_expr</replaceable> is
any variable-free expression (subqueries, window functions, aggregate
functions, and set-returning functions are not allowed). Its data type
must match the data type of the corresponding partition key column.
The expression is evaluated once at table creation time, so it can
even contain volatile expressions such as
<literal><function>CURRENT_TIMESTAMP</function></literal>.
Docs: improve CREATE TABLE ref page's discussion of partition bounds. Clarify in the syntax synopsis that partition bound values must be exactly numeric literals or string literals; previously it said "bound_literal" which was defined nowhere. Replace confusing --- and, I think, incorrect in detail --- definition of how range bounds work with a reference to row-wise comparison plus a concrete example (which I stole from Robert Haas). Minor copy-editing in the same area. Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
2017-06-07 23:23:38 +02:00
</para>
<para>
When creating a list partition, <literal>NULL</literal> can be
specified to signify that the partition allows the partition key
column to be null. However, there cannot be more than one such
list partition for a given parent table. <literal>NULL</literal>
cannot be specified for range partitions.
Tidy up the CREATE TABLE documentation for partitioning. Remove some <note> tags that make this too "loud". Fix some typos. Amit Langote, with a few minor corrections by me Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:00:09 +02:00
</para>
<para>
When creating a range partition, the lower bound specified with
<literal>FROM</literal> is an inclusive bound, whereas the upper
bound specified with <literal>TO</literal> is an exclusive bound.
That is, the values specified in the <literal>FROM</literal> list
Docs: improve CREATE TABLE ref page's discussion of partition bounds. Clarify in the syntax synopsis that partition bound values must be exactly numeric literals or string literals; previously it said "bound_literal" which was defined nowhere. Replace confusing --- and, I think, incorrect in detail --- definition of how range bounds work with a reference to row-wise comparison plus a concrete example (which I stole from Robert Haas). Minor copy-editing in the same area. Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
2017-06-07 23:23:38 +02:00
are valid values of the corresponding partition key columns for this
partition, whereas those in the <literal>TO</literal> list are
not. Note that this statement must be understood according to the
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
rules of row-wise comparison (<xref linkend="row-wise-comparison"/>).
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
For example, given <literal>PARTITION BY RANGE (x,y)</literal>, a partition
Docs: improve CREATE TABLE ref page's discussion of partition bounds. Clarify in the syntax synopsis that partition bound values must be exactly numeric literals or string literals; previously it said "bound_literal" which was defined nowhere. Replace confusing --- and, I think, incorrect in detail --- definition of how range bounds work with a reference to row-wise comparison plus a concrete example (which I stole from Robert Haas). Minor copy-editing in the same area. Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
2017-06-07 23:23:38 +02:00
bound <literal>FROM (1, 2) TO (3, 4)</literal>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
allows <literal>x=1</literal> with any <literal>y&gt;=2</literal>,
<literal>x=2</literal> with any non-null <literal>y</literal>,
and <literal>x=3</literal> with any <literal>y&lt;4</literal>.
Tidy up the CREATE TABLE documentation for partitioning. Remove some <note> tags that make this too "loud". Fix some typos. Amit Langote, with a few minor corrections by me Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:00:09 +02:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The special values <literal>MINVALUE</literal> and <literal>MAXVALUE</literal>
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
may be used when creating a range partition to indicate that there
is no lower or upper bound on the column's value. For example, a
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
partition defined using <literal>FROM (MINVALUE) TO (10)</literal> allows
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
any values less than 10, and a partition defined using
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>FROM (10) TO (MAXVALUE)</literal> allows any values greater than
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
or equal to 10.
</para>
<para>
When creating a range partition involving more than one column, it
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
can also make sense to use <literal>MAXVALUE</literal> as part of the lower
bound, and <literal>MINVALUE</literal> as part of the upper bound. For
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
example, a partition defined using
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>FROM (0, MAXVALUE) TO (10, MAXVALUE)</literal> allows any rows
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
where the first partition key column is greater than 0 and less than
or equal to 10. Similarly, a partition defined using
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>FROM ('a', MINVALUE) TO ('b', MINVALUE)</literal> allows any rows
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
where the first partition key column starts with "a".
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Note that if <literal>MINVALUE</literal> or <literal>MAXVALUE</literal> is used for
After a MINVALUE/MAXVALUE bound, allow only more of the same. In the old syntax, which used UNBOUNDED, we had a similar restriction, but commit d363d42bb9a4399a0207bd3b371c966e22e06bd3, which changed the syntax, eliminated it. Put it back. Patch by me, reviewed by Dean Rasheed. Discussion: http://postgr.es/m/CA+Tgmobs+pLPC27tS3gOpEAxAffHrq5w509cvkwTf9pF6cWYbg@mail.gmail.com
2017-09-16 03:15:55 +02:00
one column of a partitioning bound, the same value must be used for all
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
subsequent columns. For example, <literal>(10, MINVALUE, 0)</literal> is not
a valid bound; you should write <literal>(10, MINVALUE, MINVALUE)</literal>.
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Also note that some element types, such as <literal>timestamp</literal>,
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
have a notion of "infinity", which is just another value that can
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
be stored. This is different from <literal>MINVALUE</literal> and
<literal>MAXVALUE</literal>, which are not real values that can be stored,
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
but rather they are ways of saying that the value is unbounded.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>MAXVALUE</literal> can be thought of as being greater than any
other value, including "infinity" and <literal>MINVALUE</literal> as being
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
less than any other value, including "minus infinity". Thus the range
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>FROM ('infinity') TO (MAXVALUE)</literal> is not an empty range; it
Use MINVALUE/MAXVALUE instead of UNBOUNDED for range partition bounds. Previously, UNBOUNDED meant no lower bound when used in the FROM list, and no upper bound when used in the TO list, which was OK for single-column range partitioning, but problematic with multiple columns. For example, an upper bound of (10.0, UNBOUNDED) would not be collocated with a lower bound of (10.0, UNBOUNDED), thus making it difficult or impossible to define contiguous multi-column range partitions in some cases. Fix this by using MINVALUE and MAXVALUE instead of UNBOUNDED to represent a partition column that is unbounded below or above respectively. This syntax removes any ambiguity, and ensures that if one partition's lower bound equals another partition's upper bound, then the partitions are contiguous. Also drop the constraint prohibiting finite values after an unbounded column, and just document the fact that any values after MINVALUE or MAXVALUE are ignored. Previously it was necessary to repeat UNBOUNDED multiple times, which was needlessly verbose. Note: Forces a post-PG 10 beta2 initdb. Report by Amul Sul, original patch by Amit Langote with some additional hacking by me. Discussion: https://postgr.es/m/CAAJ_b947mowpLdxL3jo3YLKngRjrq9+Ej4ymduQTfYR+8=YAYQ@mail.gmail.com
2017-07-21 10:20:47 +02:00
allows precisely one value to be stored &mdash; "infinity".
Tidy up the CREATE TABLE documentation for partitioning. Remove some <note> tags that make this too "loud". Fix some typos. Amit Langote, with a few minor corrections by me Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:00:09 +02:00
</para>
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
<para>
If <literal>DEFAULT</literal> is specified, the table will be
Clarify the default partition's role Reviewed by Tom Lane and Amit Langote Discussion: https://postgr.es/m/20190806222735.GA9535@alvherre.pgsql
2019-08-08 22:03:14 +02:00
created as the default partition of the parent table. This option
is not available for hash-partitioned tables. A partition key value
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
not fitting into any other partition of the given parent will be
Clarify the default partition's role Reviewed by Tom Lane and Amit Langote Discussion: https://postgr.es/m/20190806222735.GA9535@alvherre.pgsql
2019-08-08 22:03:14 +02:00
routed to the default partition.
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
</para>
<para>
When a table has an existing <literal>DEFAULT</literal> partition and
Clarify the default partition's role Reviewed by Tom Lane and Amit Langote Discussion: https://postgr.es/m/20190806222735.GA9535@alvherre.pgsql
2019-08-08 22:03:14 +02:00
a new partition is added to it, the default partition must
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
be scanned to verify that it does not contain any rows which properly
belong in the new partition. If the default partition contains a
large number of rows, this may be slow. The scan will be skipped if
the default partition is a foreign table or if it has a constraint which
proves that it cannot contain rows which should be placed in the new
partition.
</para>
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
<para>
When creating a hash partition, a modulus and remainder must be specified.
The modulus must be a positive integer, and the remainder must be a
non-negative integer less than the modulus. Typically, when initially
setting up a hash-partitioned table, you should choose a modulus equal to
the number of partitions and assign every table the same modulus and a
different remainder (see examples, below). However, it is not required
that every partition have the same modulus, only that every modulus which
occurs among the partitions of a hash-partitioned table is a factor of the
next larger modulus. This allows the number of partitions to be increased
incrementally without needing to move all the data at once. For example,
suppose you have a hash-partitioned table with 8 partitions, each of which
has modulus 8, but find it necessary to increase the number of partitions
to 16. You can detach one of the modulus-8 partitions, create two new
modulus-16 partitions covering the same portion of the key space (one with
a remainder equal to the remainder of the detached partition, and the
other with a remainder equal to that value plus 8), and repopulate them
with data. You can then repeat this -- perhaps at a later time -- for
each modulus-8 partition until none remain. While this may still involve
a large amount of data movement at each step, it is still better than
having to create a whole new table and move all the data at once.
</para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Make partitions automatically inherit OIDs. Previously, if the parent was specified as WITH OIDS, each child also had to be explicitly specified as WITH OIDS. Amit Langote, per a report from Simon Riggs. Some additional work on the documentation changes by me. Discussion: http://postgr.es/m/CANP8+jJBpWocfKrbJcaf3iBt9E3U=WPE_NC8YE6rye+YJ1sYnQ@mail.gmail.com
2017-02-19 16:59:27 +01:00
A partition must have the same column names and types as the partitioned
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
table to which it belongs. Modifications to the column names or types of
a partitioned table will automatically propagate to all partitions.
<literal>CHECK</literal> constraints will be inherited automatically by
every partition, but an individual partition may specify additional
<literal>CHECK</literal> constraints; additional constraints with the
same name and condition as in the parent will be merged with the parent
constraint. Defaults may be specified separately for each partition.
Add note about how each partition's default value is treated, into the doc. Column defaults may be specified separately for each partition. But INSERT via a partitioned table ignores those partition's default values. The former is documented, but the latter restriction not. This commit adds the note about that restriction into the document. Author: Fujii Masao Reviewed-by: Amit Langote Discussion: https://postgr.es/m/CAHGQGwEs-59omrfGF7hOHz9iMME3RbKy5ny+iftDx3LHTEn9sA@mail.gmail.com
2019-12-26 07:07:43 +01:00
But note that a partition's default value is not applied when inserting
a tuple through a partitioned table.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
<para>
Rows inserted into a partitioned table will be automatically routed to
the correct partition. If no suitable partition exists, an error will
Documentation updates for partitioning. Takayuki Tsunakawa Discussion: http://postgr.es/m/0A3221C70F24FB45833433255569204D1F965627@G01JPEXMBYT05
2018-05-07 15:48:47 +02:00
occur.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
<para>
Doc: mention CREATE+ATTACH PARTITION with CREATE TABLE...PARTITION OF. Clarify that ATTACH/DETACH PARTITION can be used to perform partition maintenance with less locking than straight CREATE TABLE/DROP TABLE. This was already stated in some places, but not emphasized. Back-patch to v14 where DETACH PARTITION CONCURRENTLY was added. (We had lower lock levels for ATTACH PARTITION before that, but this wording wouldn't apply.) Justin Pryzby, reviewed by Robert Treat and Jakub Wartak; a little further wordsmithing by me Discussion: https://postgr.es/m/20220718143304.GC18011@telsasoft.com
2023-03-16 21:50:56 +01:00
Operations such as <command>TRUNCATE</command>
which normally affect a table and all of its
Make partitions automatically inherit OIDs. Previously, if the parent was specified as WITH OIDS, each child also had to be explicitly specified as WITH OIDS. Amit Langote, per a report from Simon Riggs. Some additional work on the documentation changes by me. Discussion: http://postgr.es/m/CANP8+jJBpWocfKrbJcaf3iBt9E3U=WPE_NC8YE6rye+YJ1sYnQ@mail.gmail.com
2017-02-19 16:59:27 +01:00
inheritance children will cascade to all partitions, but may also be
Doc: mention CREATE+ATTACH PARTITION with CREATE TABLE...PARTITION OF. Clarify that ATTACH/DETACH PARTITION can be used to perform partition maintenance with less locking than straight CREATE TABLE/DROP TABLE. This was already stated in some places, but not emphasized. Back-patch to v14 where DETACH PARTITION CONCURRENTLY was added. (We had lower lock levels for ATTACH PARTITION before that, but this wording wouldn't apply.) Justin Pryzby, reviewed by Robert Treat and Jakub Wartak; a little further wordsmithing by me Discussion: https://postgr.es/m/20220718143304.GC18011@telsasoft.com
2023-03-16 21:50:56 +01:00
performed on an individual partition.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
Doc: mention CREATE+ATTACH PARTITION with CREATE TABLE...PARTITION OF. Clarify that ATTACH/DETACH PARTITION can be used to perform partition maintenance with less locking than straight CREATE TABLE/DROP TABLE. This was already stated in some places, but not emphasized. Back-patch to v14 where DETACH PARTITION CONCURRENTLY was added. (We had lower lock levels for ATTACH PARTITION before that, but this wording wouldn't apply.) Justin Pryzby, reviewed by Robert Treat and Jakub Wartak; a little further wordsmithing by me Discussion: https://postgr.es/m/20220718143304.GC18011@telsasoft.com
2023-03-16 21:50:56 +01:00
<para>
Note that creating a partition using <literal>PARTITION OF</literal>
requires taking an <literal>ACCESS EXCLUSIVE</literal> lock on the
parent partitioned table. Likewise, dropping a partition
with <command>DROP TABLE</command> requires taking
an <literal>ACCESS EXCLUSIVE</literal> lock on the parent table.
It is possible to use <link linkend="sql-altertable"><command>ALTER
TABLE ATTACH/DETACH PARTITION</command></link> to perform these
operations with a weaker lock, thus reducing interference with
concurrent operations on the partitioned table.
</para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like">
Rename the internal structures of the CREATE TABLE (LIKE ...) facility The original implementation of this interpreted it as a kind of "inheritance" facility and named all the internal structures accordingly. This turned out to be very confusing, because it has nothing to do with the INHERITS feature. So rename all the internal parser infrastructure, update the comments, adjust the error messages, and split up the regression tests.
2012-01-07 13:58:13 +01:00
<term><literal>LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ]</literal></term>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
<listitem>
<para>
The <literal>LIKE</literal> clause specifies a table from which
the new table automatically copies all column names, their data types,
and their not-null constraints.
</para>
<para>
Unlike <literal>INHERITS</literal>, the new table and original table
are completely decoupled after creation is complete. Changes to the
original table will not be applied to the new table, and it is not
possible to include data of the new table in scans of the original
table.
</para>
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<para>
Also unlike <literal>INHERITS</literal>, columns and
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
constraints copied by <literal>LIKE</literal> are not merged with similarly
Code review for LIKE INCLUDING patch --- clean up some cosmetic and not so cosmetic stuff.
2009-10-13 02:53:08 +02:00
named columns and constraints.
Add INCLUDING CONSTRAINTS to CREATE TABLE LIKE. Greg Stark
2006-06-27 05:43:20 +02:00
If the same name is specified explicitly or in another
Documentation spell checking and markup improvements
2013-05-21 03:13:13 +02:00
<literal>LIKE</literal> clause, an error is signaled.
Add INCLUDING CONSTRAINTS to CREATE TABLE LIKE. Greg Stark
2006-06-27 05:43:20 +02:00
</para>
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<para>
The optional <replaceable>like_option</replaceable> clauses specify
which additional properties of the original table to copy. Specifying
<literal>INCLUDING</literal> copies the property, specifying
<literal>EXCLUDING</literal> omits the property.
<literal>EXCLUDING</literal> is the default. If multiple specifications
are made for the same kind of object, the last one is used. The
available options are:
<variablelist>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-comments">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING COMMENTS</literal></term>
<listitem>
<para>
Comments for the copied columns, constraints, and indexes will be
copied. The default behavior is to exclude comments, resulting in
the copied columns and constraints in the new table having no
comments.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-compression">
Allow configurable LZ4 TOAST compression. There is now a per-column COMPRESSION option which can be set to pglz (the default, and the only option in up until now) or lz4. Or, if you like, you can set the new default_toast_compression GUC to lz4, and then that will be the default for new table columns for which no value is specified. We don't have lz4 support in the PostgreSQL code, so to use lz4 compression, PostgreSQL must be built --with-lz4. In general, TOAST compression means compression of individual column values, not the whole tuple, and those values can either be compressed inline within the tuple or compressed and then stored externally in the TOAST table, so those properties also apply to this feature. Prior to this commit, a TOAST pointer has two unused bits as part of the va_extsize field, and a compessed datum has two unused bits as part of the va_rawsize field. These bits are unused because the length of a varlena is limited to 1GB; we now use them to indicate the compression type that was used. This means we only have bit space for 2 more built-in compresison types, but we could work around that problem, if necessary, by introducing a new vartag_external value for any further types we end up wanting to add. Hopefully, it won't be too important to offer a wide selection of algorithms here, since each one we add not only takes more coding but also adds a build dependency for every packager. Nevertheless, it seems worth doing at least this much, because LZ4 gets better compression than PGLZ with less CPU usage. It's possible for LZ4-compressed datums to leak into composite type values stored on disk, just as it is for PGLZ. It's also possible for LZ4-compressed attributes to be copied into a different table via SQL commands such as CREATE TABLE AS or INSERT .. SELECT. It would be expensive to force such values to be decompressed, so PostgreSQL has never done so. For the same reasons, we also don't force recompression of already-compressed values even if the target table prefers a different compression method than was used for the source data. These architectural decisions are perhaps arguable but revisiting them is well beyond the scope of what seemed possible to do as part of this project. However, it's relatively cheap to recompress as part of VACUUM FULL or CLUSTER, so this commit adjusts those commands to do so, if the configured compression method of the table happens not to match what was used for some column value stored therein. Dilip Kumar. The original patches on which this work was based were written by Ildus Kurbangaliev, and those were patches were based on even earlier work by Nikita Glukhov, but the design has since changed very substantially, since allow a potentially large number of compression methods that could be added and dropped on a running system proved too problematic given some of the architectural issues mentioned above; the choice of which specific compression method to add first is now different; and a lot of the code has been heavily refactored. More recently, Justin Przyby helped quite a bit with testing and reviewing and this version also includes some code contributions from him. Other design input and review from Tomas Vondra, Álvaro Herrera, Andres Freund, Oleg Bartunov, Alexander Korotkov, and me. Discussion: http://postgr.es/m/20170907194236.4cefce96%40wp.localdomain Discussion: http://postgr.es/m/CAFiTN-uUpX3ck%3DK0mLEk-G_kUQY%3DSNOTeqdaNRR9FMdQrHKebw%40mail.gmail.com
2021-03-19 20:10:38 +01:00
<term><literal>INCLUDING COMPRESSION</literal></term>
<listitem>
<para>
Compression method of the columns will be copied. The default
behavior is to exclude compression methods, resulting in columns
having the default compression method.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-constraints">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING CONSTRAINTS</literal></term>
<listitem>
<para>
<literal>CHECK</literal> constraints will be copied. No distinction
is made between column constraints and table constraints. Not-null
constraints are always copied to the new table.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-defaults">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING DEFAULTS</literal></term>
<listitem>
<para>
Default expressions for the copied column definitions will be
copied. Otherwise, default expressions are not copied, resulting in
the copied columns in the new table having null defaults. Note that
copying defaults that call database-modification functions, such as
<function>nextval</function>, may create a functional linkage
between the original and new tables.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-generated">
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
<term><literal>INCLUDING GENERATED</literal></term>
<listitem>
<para>
Any generation expressions of copied column definitions will be
copied. By default, new columns will be regular base columns.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-identity">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING IDENTITY</literal></term>
<listitem>
<para>
Any identity specifications of copied column definitions will be
copied. A new sequence is created for each identity column of the
new table, separate from the sequences associated with the old
table.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-indexes">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING INDEXES</literal></term>
<listitem>
<para>
Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
and <literal>EXCLUDE</literal> constraints on the original table
will be created on the new table. Names for the new indexes and
constraints are chosen according to the default rules, regardless of
how the originals were named. (This behavior avoids possible
duplicate-name failures for the new indexes.)
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-statistics">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING STATISTICS</literal></term>
<listitem>
<para>
Extended statistics are copied to the new table.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-storage">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING STORAGE</literal></term>
<listitem>
<para>
<literal>STORAGE</literal> settings for the copied column
definitions will be copied. The default behavior is to exclude
<literal>STORAGE</literal> settings, resulting in the copied columns
in the new table having type-specific default settings. For more on
<literal>STORAGE</literal> settings, see <xref
linkend="storage-toast"/>.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-like-opt-all">
doc: Reorganize CREATE TABLE / LIKE option documentation This section once started out small but has now grown quite a bit and needs a bit of structure. Rewrite as list, add documentation of EXCLUDING, and improve the documentation of INCLUDING ALL instead of just listing all the options again. per report from Yugo Nagata that EXCLUDING was not documented, that part reviewed by Daniel Gustafsson, most of the rewrite was by me
2018-07-04 10:40:16 +02:00
<term><literal>INCLUDING ALL</literal></term>
<listitem>
<para>
<literal>INCLUDING ALL</literal> is an abbreviated form selecting
all the available individual options. (It could be useful to write
individual <literal>EXCLUDING</literal> clauses after
<literal>INCLUDING ALL</literal> to select all but some specific
options.)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
Support CREATE TABLE (LIKE ...) with foreign tables and views Composite types are not yet supported, because parserOpenTable() rejects them.
2012-01-10 20:46:29 +01:00
<para>
Improve documentation about CREATE TABLE ... LIKE. The docs failed to explain that LIKE INCLUDING INDEXES would not preserve the names of indexes and associated constraints. Also, it wasn't mentioned that EXCLUDE constraints would be copied by this option. The latter oversight seems enough of a documentation bug to justify back-patching. In passing, do some minor copy-editing in the same area, and add an entry for LIKE under "Compatibility", since it's not exactly a faithful implementation of the standard's feature. Discussion: <20160728151154.AABE64016B@smtp.hushmail.com>
2016-07-28 19:26:58 +02:00
The <literal>LIKE</literal> clause can also be used to copy column
definitions from views, foreign tables, or composite types.
Inapplicable options (e.g., <literal>INCLUDING INDEXES</literal> from
a view) are ignored.
Support CREATE TABLE (LIKE ...) with foreign tables and views Composite types are not yet supported, because parserOpenTable() rejects them.
2012-01-10 20:46:29 +01:00
</para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-constraint">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>CONSTRAINT <replaceable class="parameter">constraint_name</replaceable></literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Add documentaiotn mention that constraint names can be sentences that can convey information to clients on constraint violation.
2006-01-16 20:50:03 +01:00
An optional name for a column or table constraint. If the
constraint is violated, the constraint name is present in error messages,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
so constraint names like <literal>col must be positive</literal> can be used
Add markup for new constraint_name mention.
2006-01-16 20:53:12 +01:00
to communicate helpful constraint information to client applications.
Improve constraint_name wording.
2006-01-16 21:48:49 +01:00
(Double-quotes are needed to specify constraint names that contain spaces.)
If a constraint name is not specified, the system generates a name.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-not-null">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>NOT NULL</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
The column is not allowed to contain null values.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-null">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>NULL</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
The column is allowed to contain null values. This is the default.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
This clause is only provided for compatibility with
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
non-standard SQL databases. Its use is discouraged in new
applications.
</para>
</listitem>
</varlistentry>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-check">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </literal></term>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
<listitem>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>CHECK</literal> clause specifies an expression producing a
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Boolean result which new or updated rows must satisfy for an
insert or update operation to succeed. Expressions evaluating
to TRUE or UNKNOWN succeed. Should any row of an insert or
doc: add comma for clarity Patch by Etsuro Fujita
2015-03-20 21:58:19 +01:00
update operation produce a FALSE result, an error exception is
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
raised and the insert or update does not alter the database. A
check constraint specified as a column constraint should
reference that column's value only, while an expression
appearing in a table constraint can reference multiple columns.
</para>
<para>
Currently, <literal>CHECK</literal> expressions cannot contain
subqueries nor refer to variables other than columns of the
Clarify that cross-row constraints are unsupported Maybe we'll implement them later, or maybe not, but let's make the statu quo clear for now. Author: Lætitia Avrot, Patrick Francelle Reviewers: too many to list Discussion: https://postgr.es/m/CAB_COdhUuzNFOJfc7SNNso5rOuVA3ui93KMVunEM8Yih+K5A6A@mail.gmail.com
2018-11-26 16:27:07 +01:00
current row (see <xref linkend="ddl-constraints-check-constraints"/>).
The system column <literal>tableoid</literal>
Don't allow system columns in CHECK constraints, except tableoid. Previously, arbitray system columns could be mentioned in table constraints, but they were not correctly checked at runtime, because the values weren't actually set correctly in the tuple. Since it seems easy enough to initialize the table OID properly, do that, and continue allowing that column, but disallow the rest unless and until someone figures out a way to make them work properly. No back-patch, because this doesn't seem important enough to take the risk of destabilizing the back branches. In fact, this will pose a dump-and-reload hazard for those upgrading from previous versions: constraints that were accepted before but were not correctly enforced will now either be enforced correctly or not accepted at all. Either could result in restore failures, but in practice I think very few users will notice the difference, since the use case is pretty marginal anyway and few users will be relying on features that have not historically worked. Amit Kapila, reviewed by Rushabh Lathia, with doc changes by me.
2013-09-23 19:31:22 +02:00
may be referenced, but not any other system column.
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
</para>
Recast "ONLY" column CHECK constraints as NO INHERIT The original syntax wasn't universally loved, and it didn't allow its usage in CREATE TABLE, only ALTER TABLE. It now works everywhere, and it also allows using ALTER TABLE ONLY to add an uninherited CHECK constraint, per discussion. The pg_constraint column has accordingly been renamed connoinherit. This commit partly reverts some of the changes in 61d81bd28dbec65a6b144e0cd3d0bfe25913c3ac, particularly some pg_dump and psql bits, because now pg_get_constraintdef includes the necessary NO INHERIT within the constraint definition. Author: Nikhil Sontakke Some tweaks by me
2012-04-21 04:46:20 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
A constraint marked with <literal>NO INHERIT</literal> will not propagate to
Minor improvements for CHECK NO INHERIT documentation. Fix typo spotted by Thom Brown, and improve wording in another area where Thom spotted a typo.
2012-04-24 03:59:17 +02:00
child tables.
Recast "ONLY" column CHECK constraints as NO INHERIT The original syntax wasn't universally loved, and it didn't allow its usage in CREATE TABLE, only ALTER TABLE. It now works everywhere, and it also allows using ALTER TABLE ONLY to add an uninherited CHECK constraint, per discussion. The pg_constraint column has accordingly been renamed connoinherit. This commit partly reverts some of the changes in 61d81bd28dbec65a6b144e0cd3d0bfe25913c3ac, particularly some pg_dump and psql bits, because now pg_get_constraintdef includes the necessary NO INHERIT within the constraint definition. Author: Nikhil Sontakke Some tweaks by me
2012-04-21 04:46:20 +02:00
</para>
Apply table and domain CHECK constraints in name order. Previously, CHECK constraints of the same scope were checked in whatever order they happened to be read from pg_constraint. (Usually, but not reliably, this would be creation order for domain constraints and reverse creation order for table constraints, because of differing implementation details.) Nondeterministic results of this sort are problematic at least for testing purposes, and in discussion it was agreed to be a violation of the principle of least astonishment. Therefore, borrow the principle already established for triggers, and apply such checks in name order (using strcmp() sort rules). This lets users control the check order if they have a mind to. Domain CHECK constraints still follow the rule of checking lower nested domains' constraints first; the name sort only applies to multiple constraints attached to the same domain. In passing, I failed to resist the temptation to wordsmith a bit in create_domain.sgml. Apply to HEAD only, since this could result in a behavioral change in existing applications, and the potential regression test failures have not actually been observed in our buildfarm.
2015-03-23 21:59:29 +01:00
<para>
When a table has multiple <literal>CHECK</literal> constraints,
they will be tested for each row in alphabetical order by name,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
after checking <literal>NOT NULL</literal> constraints.
(<productname>PostgreSQL</productname> versions before 9.5 did not honor any
Apply table and domain CHECK constraints in name order. Previously, CHECK constraints of the same scope were checked in whatever order they happened to be read from pg_constraint. (Usually, but not reliably, this would be creation order for domain constraints and reverse creation order for table constraints, because of differing implementation details.) Nondeterministic results of this sort are problematic at least for testing purposes, and in discussion it was agreed to be a violation of the principle of least astonishment. Therefore, borrow the principle already established for triggers, and apply such checks in name order (using strcmp() sort rules). This lets users control the check order if they have a mind to. Domain CHECK constraints still follow the rule of checking lower nested domains' constraints first; the name sort only applies to multiple constraints attached to the same domain. In passing, I failed to resist the temptation to wordsmith a bit in create_domain.sgml. Apply to HEAD only, since this could result in a behavioral change in existing applications, and the potential regression test failures have not actually been observed in our buildfarm.
2015-03-23 21:59:29 +01:00
particular firing order for <literal>CHECK</literal> constraints.)
</para>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-default">
Reclassify DEFAULT as a column_constraint item in the CREATE TABLE syntax. This is how it was documented originally, but several years ago somebody decided that DEFAULT isn't a type of constraint. Well, the grammar thinks it is. The documentation was wrong in two ways: it alleged that DEFAULT had to appear before any other kind of constraint, and it alleged that you can't prefix a DEFAULT clause with a "CONSTRAINT name" clause, when in fact you can. (The latter behavior probably isn't SQL-standard, but our grammar has always allowed it.) This patch responds to Fujii Masao's observation that the ALTER TABLE documentation mistakenly implied that you couldn't include DEFAULT in ALTER TABLE ADD COLUMN; though this isn't the way he proposed fixing it.
2010-12-29 03:38:05 +01:00
<term><literal>DEFAULT
<replaceable>default_expr</replaceable></literal></term>
<listitem>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>DEFAULT</literal> clause assigns a default data value for
Reclassify DEFAULT as a column_constraint item in the CREATE TABLE syntax. This is how it was documented originally, but several years ago somebody decided that DEFAULT isn't a type of constraint. Well, the grammar thinks it is. The documentation was wrong in two ways: it alleged that DEFAULT had to appear before any other kind of constraint, and it alleged that you can't prefix a DEFAULT clause with a "CONSTRAINT name" clause, when in fact you can. (The latter behavior probably isn't SQL-standard, but our grammar has always allowed it.) This patch responds to Fujii Masao's observation that the ALTER TABLE documentation mistakenly implied that you couldn't include DEFAULT in ALTER TABLE ADD COLUMN; though this isn't the way he proposed fixing it.
2010-12-29 03:38:05 +01:00
the column whose column definition it appears within. The value
Improve error handling of column references in expression transformation Column references are not allowed in default expressions and partition bound expressions, and are restricted as such once the transformation of their expressions is done. However, trying to use more complex column references can lead to confusing error messages. For example, trying to use a two-field column reference name for default expressions and partition bounds leads to "missing FROM-clause entry for table", which makes no sense in their respective context. In order to make the errors generated more useful, this commit adds more verbose messages when transforming column references depending on the context. This has a little consequence though: for example an expression using an aggregate with a column reference as argument would cause an error to be generated for the column reference, while the aggregate was the problem reported before this commit because column references get transformed first. The confusion exists for default expressions for a long time, and the problem is new as of v12 for partition bounds. Still per the lack of complaints on the matter no backpatch is done. The patch has been written by Amit Langote and me, and Tom Lane has provided the improvement of the documentation for default expressions on the CREATE TABLE page. Author: Amit Langote, Michael Paquier Reviewed-by: Tom Lane Discussion: https://postgr.es/m/20190326020853.GM2558@paquier.xyz
2019-03-27 13:04:25 +01:00
is any variable-free expression (in particular, cross-references
to other columns in the current table are not allowed). Subqueries
are not allowed either. The data type of the default expression must
match the data type of the column.
Reclassify DEFAULT as a column_constraint item in the CREATE TABLE syntax. This is how it was documented originally, but several years ago somebody decided that DEFAULT isn't a type of constraint. Well, the grammar thinks it is. The documentation was wrong in two ways: it alleged that DEFAULT had to appear before any other kind of constraint, and it alleged that you can't prefix a DEFAULT clause with a "CONSTRAINT name" clause, when in fact you can. (The latter behavior probably isn't SQL-standard, but our grammar has always allowed it.) This patch responds to Fujii Masao's observation that the ALTER TABLE documentation mistakenly implied that you couldn't include DEFAULT in ALTER TABLE ADD COLUMN; though this isn't the way he proposed fixing it.
2010-12-29 03:38:05 +01:00
</para>
<para>
The default expression will be used in any insert operation that
does not specify a value for the column. If there is no default
for a column, then the default is null.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-generated-stored">
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
<term><literal>GENERATED ALWAYS AS ( <replaceable>generation_expr</replaceable> ) STORED</literal><indexterm><primary>generated column</primary></indexterm></term>
<listitem>
<para>
This clause creates the column as a <firstterm>generated
doc: Fix generated column documentation The old text still had an implicit reference to the virtual behavior, which was not in the final patch. Author: Tobias Bussmann <t.bussmann@gmx.net>
2019-05-27 18:26:16 +02:00
column</firstterm>. The column cannot be written to, and when read the
result of the specified expression will be returned.
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
</para>
<para>
The keyword <literal>STORED</literal> is required to signify that the
doc: Fix typo Author: Justin Pryzby <pryzby@telsasoft.com>
2019-03-30 17:25:13 +01:00
column will be computed on write and will be stored on disk.
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
</para>
<para>
The generation expression can refer to other columns in the table, but
not other generated columns. Any functions and operators used must be
immutable. References to other tables are not allowed.
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-generated-identity">
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
<term><literal>GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ]</literal></term>
<listitem>
<para>
This clause creates the column as an <firstterm>identity
column</firstterm>. It will have an implicit sequence attached to it
and the column in new rows will automatically have values from the
sequence assigned to it.
Forbid marking an identity column as nullable. GENERATED ALWAYS AS IDENTITY implies NOT NULL, but the code failed to complain if you overrode that with "GENERATED ALWAYS AS IDENTITY NULL". One might think the old behavior was a feature, but it was inconsistent because the outcome varied depending on the order of the clauses, so it seems to have been just an oversight. Per bug #16913 from Pavel Boev. Back-patch to v10 where identity columns were introduced. Vik Fearing (minor tweaks by me) Discussion: https://postgr.es/m/16913-3b5198410f67d8c6@postgresql.org
2021-03-12 17:08:42 +01:00
Such a column is implicitly <literal>NOT NULL</literal>.
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
</para>
<para>
The clauses <literal>ALWAYS</literal> and <literal>BY DEFAULT</literal>
Fix INSERT OVERRIDING USER VALUE behavior The original implementation disallowed using OVERRIDING USER VALUE on identity columns defined as GENERATED ALWAYS, which is not per standard. So allow that now. Expand documentation and tests around this. Author: Dean Rasheed <dean.a.rasheed@gmail.com> Reviewed-by: Peter Eisentraut <peter.eisentraut@2ndquadrant.com> Reviewed-by: Vik Fearing <vik@postgresfriends.org> Discussion: https://www.postgresql.org/message-id/flat/CAEZATCVrh2ufCwmzzM%3Dk_OfuLhTTPBJCdFkimst2kry4oHepuQ%40mail.gmail.com
2020-03-31 08:40:32 +02:00
determine how explicitly user-specified values are handled in
<command>INSERT</command> and <command>UPDATE</command> commands.
</para>
<para>
In an <command>INSERT</command> command, if <literal>ALWAYS</literal> is
selected, a user-specified value is only accepted if the
<command>INSERT</command> statement specifies <literal>OVERRIDING SYSTEM
VALUE</literal>. If <literal>BY DEFAULT</literal> is selected, then the
user-specified value takes precedence. See <xref linkend="sql-insert"/>
for details. (In the <command>COPY</command> command, user-specified
values are always used regardless of this setting.)
</para>
<para>
In an <command>UPDATE</command> command, if <literal>ALWAYS</literal> is
selected, any update of the column to any value other than
<literal>DEFAULT</literal> will be rejected. If <literal>BY
DEFAULT</literal> is selected, the column can be updated normally.
(There is no <literal>OVERRIDING</literal> clause for the
<command>UPDATE</command> command.)
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
</para>
<para>
The optional <replaceable>sequence_options</replaceable> clause can be
used to override the options of the sequence.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
See <xref linkend="sql-createsequence"/> for details.
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-unique">
Add UNIQUE null treatment option The SQL standard has been ambiguous about whether null values in unique constraints should be considered equal or not. Different implementations have different behaviors. In the SQL:202x draft, this has been formalized by making this implementation-defined and adding an option on unique constraint definitions UNIQUE [ NULLS [NOT] DISTINCT ] to choose a behavior explicitly. This patch adds this option to PostgreSQL. The default behavior remains UNIQUE NULLS DISTINCT. Making this happen in the btree code is pretty easy; most of the patch is just to carry the flag around to all the places that need it. The CREATE UNIQUE INDEX syntax extension is not from the standard, it's my own invention. I named all the internal flags, catalog columns, etc. in the negative ("nulls not distinct") so that the default PostgreSQL behavior is the default if the flag is false. Reviewed-by: Maxim Orlov <orlovmg@gmail.com> Reviewed-by: Pavel Borisov <pashkin.elfe@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/84e5ee1b-387e-9a54-c326-9082674bde78@enterprisedb.com
2022-02-03 11:29:54 +01:00
<term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ]</literal> (column constraint)</term>
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
<term><literal>UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal>
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
<optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term>
Revert CREATE INDEX ... INCLUDING ... It's not ready yet, revert two commits 690c543550b0d2852060c18d270cdb534d339d9a - unstable test output 386e3d7609c49505e079c40c65919d99feb82505 - patch itself
2016-04-08 20:52:13 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
The <literal>UNIQUE</literal> constraint specifies that a
Update reference 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".
2007-02-01 00:26:05 +01:00
group of one or more columns of a table can contain
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
only unique values. The behavior of a unique table constraint
is the same as that of a unique column constraint, with the
additional capability to span multiple columns. The constraint
therefore enforces that any two rows must differ in at least one
of these columns.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
<para>
If the <literal>WITHOUT OVERLAPS</literal> option is specified for the
last column, then that column is checked for overlaps instead of
equality. In that case, the other columns of the constraint will allow
duplicates so long as the duplicates don't overlap in the
<literal>WITHOUT OVERLAPS</literal> column. (This is sometimes called a
temporal key, if the column is a range of dates or timestamps, but
PostgreSQL allows ranges over any base type.) In effect, such a
constraint is enforced with an <literal>EXCLUDE</literal> constraint
rather than a <literal>UNIQUE</literal> constraint. So for example
<literal>UNIQUE (id, valid_at WITHOUT OVERLAPS)</literal> behaves like
<literal>EXCLUDE USING GIST (id WITH =, valid_at WITH
&amp;&amp;)</literal>. The <literal>WITHOUT OVERLAPS</literal> column
must have a range or multirange type. (Technically, any type is allowed
whose default GiST opclass includes an overlaps operator. See the
<literal>stratnum</literal> support function under <xref
linkend="gist-extensibility"/> for details.) The non-<literal>WITHOUT
OVERLAPS</literal> columns of the constraint can be any type that can be
compared for equality in a GiST index. By default, only range types are
supported, but you can use other types by adding the <xref
linkend="btree-gist"/> extension (which is the expected way to use this
feature).
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
For the purpose of a unique constraint, null values are not
Add UNIQUE null treatment option The SQL standard has been ambiguous about whether null values in unique constraints should be considered equal or not. Different implementations have different behaviors. In the SQL:202x draft, this has been formalized by making this implementation-defined and adding an option on unique constraint definitions UNIQUE [ NULLS [NOT] DISTINCT ] to choose a behavior explicitly. This patch adds this option to PostgreSQL. The default behavior remains UNIQUE NULLS DISTINCT. Making this happen in the btree code is pretty easy; most of the patch is just to carry the flag around to all the places that need it. The CREATE UNIQUE INDEX syntax extension is not from the standard, it's my own invention. I named all the internal flags, catalog columns, etc. in the negative ("nulls not distinct") so that the default PostgreSQL behavior is the default if the flag is false. Reviewed-by: Maxim Orlov <orlovmg@gmail.com> Reviewed-by: Pavel Borisov <pashkin.elfe@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/84e5ee1b-387e-9a54-c326-9082674bde78@enterprisedb.com
2022-02-03 11:29:54 +01:00
considered equal, unless <literal>NULLS NOT DISTINCT</literal> is
specified.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Editing and markup cleanup.
1998-09-22 17:48:03 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
Each unique constraint should name a set of columns that is
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
different from the set of columns named by any other unique or
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
primary key constraint defined for the table. (Otherwise, redundant
unique constraints will be discarded.)
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
<para>
doc: Reword restriction on partition keys in unique indexes New wording from David G. Johnston, who noticed the unreadable original also. Include his suggested test case as well. Fix a typo I noticed elsewhere while doing this. Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-03-12 17:28:52 +01:00
When establishing a unique constraint for a multi-level partition
hierarchy, all the columns in the partition key of the target
partitioned table, as well as those of all its descendant partitioned
tables, must be included in the constraint definition.
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
</para>
Indexes with INCLUDE columns and their support in B-tree This patch introduces INCLUDE clause to index definition. This clause specifies a list of columns which will be included as a non-key part in the index. The INCLUDE columns exist solely to allow more queries to benefit from index-only scans. Also, such columns don't need to have appropriate operator classes. Expressions are not supported as INCLUDE columns since they cannot be used in index-only scans. Index access methods supporting INCLUDE are indicated by amcaninclude flag in IndexAmRoutine. For now, only B-tree indexes support INCLUDE clause. In B-tree indexes INCLUDE columns are truncated from pivot index tuples (tuples located in non-leaf pages and high keys). Therefore, B-tree indexes now might have variable number of attributes. This patch also provides generic facility to support that: pivot tuples contain number of their attributes in t_tid.ip_posid. Free 13th bit of t_info is used for indicating that. This facility will simplify further support of index suffix truncation. The changes of above are backward-compatible, pg_upgrade doesn't need special handling of B-tree indexes for that. Bump catalog version Author: Anastasia Lubennikova with contribition by Alexander Korotkov and me Reviewed by: Peter Geoghegan, Tomas Vondra, Antonin Houska, Jeff Janes, David Rowley, Alexander Korotkov Discussion: https://www.postgresql.org/message-id/flat/56168952.4010101@postgrespro.ru
2018-04-07 22:00:39 +02:00
<para>
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
Adding a unique constraint will automatically create a unique B-tree
index on the column or group of columns used in the constraint. But if
the constraint includes a <literal>WITHOUT OVERLAPS</literal> clause, it
doc: Document more that relations share a namespace This was already documented in the CREATE INDEX reference, but not in the introductory "Data Definition" chapter. Also, document that the index that implements a constraint has the same name as the constraint. Author: Laurenz Albe <laurenz.albe@cybertec.at> Reviewed-by: jian he <jian.universality@gmail.com> Reviewed-by: David G. Johnston <david.g.johnston@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CACJufxFG682tYcP9aH_F-jrqq5End8MHZR77zcp1%3DDUrEsSu1Q%40mail.gmail.com
2024-01-31 11:53:56 +01:00
will use a GiST index. The created index has the same name as the unique
constraint.
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
</para>
<para>
The optional <literal>INCLUDE</literal> clause adds to that index
one or more columns that are simply <quote>payload</quote>: uniqueness
is not enforced on them, and the index cannot be searched on the basis
of those columns. However they can be retrieved by an index-only scan.
Note that although the constraint is not enforced on included columns,
it still depends on them. Consequently, some operations on such columns
doc: add commas after 'i.e.' and 'e.g.' This follows the American format, https://jakubmarian.com/comma-after-i-e-and-e-g/. There is no intention of requiring this format for future text, but making existing text consistent every few years makes sense. Discussion: https://postgr.es/m/20200825183619.GA22369@momjian.us Backpatch-through: 9.5
2020-09-01 00:33:37 +02:00
(e.g., <literal>DROP COLUMN</literal>) can cause cascaded constraint and
Drop the rule against included index columns duplicating key columns. The initial version of the included-index-column feature stated that included columns couldn't be the same as any key column of the index. While it'd be pretty silly to do that, since the included column would be entirely redundant, we've never prohibited redundant index columns before so it's not very consistent to do so here. Moreover, the prohibition was itself badly implemented, so that it failed to reject columns that were effectively identical but not spelled quite alike, as reported by Aditya Toshniwal. (Moreover, it's not hard to imagine that for some non-btree index types, such cases would be non-silly anyhow: the index might use a lossy representation for key columns but be able to support retrieval of the original form of included columns.) Hence, let's just drop the prohibition. In passing, do some copy-editing on the documentation for the included-column feature. Yugo Nagata; documentation and test corrections by me Discussion: https://postgr.es/m/CAM9w-_mhBCys4fQNfaiQKTRrVWtoFrZ-wXmDuE9Nj5y-Y7aDKQ@mail.gmail.com
2018-07-18 20:43:03 +02:00
index deletion.
Indexes with INCLUDE columns and their support in B-tree This patch introduces INCLUDE clause to index definition. This clause specifies a list of columns which will be included as a non-key part in the index. The INCLUDE columns exist solely to allow more queries to benefit from index-only scans. Also, such columns don't need to have appropriate operator classes. Expressions are not supported as INCLUDE columns since they cannot be used in index-only scans. Index access methods supporting INCLUDE are indicated by amcaninclude flag in IndexAmRoutine. For now, only B-tree indexes support INCLUDE clause. In B-tree indexes INCLUDE columns are truncated from pivot index tuples (tuples located in non-leaf pages and high keys). Therefore, B-tree indexes now might have variable number of attributes. This patch also provides generic facility to support that: pivot tuples contain number of their attributes in t_tid.ip_posid. Free 13th bit of t_info is used for indicating that. This facility will simplify further support of index suffix truncation. The changes of above are backward-compatible, pg_upgrade doesn't need special handling of B-tree indexes for that. Bump catalog version Author: Anastasia Lubennikova with contribition by Alexander Korotkov and me Reviewed by: Peter Geoghegan, Tomas Vondra, Antonin Houska, Jeff Janes, David Rowley, Alexander Korotkov Discussion: https://www.postgresql.org/message-id/flat/56168952.4010101@postgrespro.ru
2018-04-07 22:00:39 +02:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-primary-key">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>PRIMARY KEY</literal> (column constraint)</term>
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
<term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, <replaceable class="parameter">column_name</replaceable> WITHOUT OVERLAPS ] )</literal>
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
<optional> <literal>INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...])</literal> </optional> (table constraint)</term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>PRIMARY KEY</literal> constraint specifies that a column or
Improve documentation about PRIMARY KEY constraints. Get rid of the false implication that PRIMARY KEY is exactly equivalent to UNIQUE + NOT NULL. That was more-or-less true at one time in our implementation, but the standard doesn't say that, and we've grown various features (many of them required by spec) that treat a pkey differently from less-formal constraints. Per recent discussion on pgsql-general. I failed to resist the temptation to do some other wordsmithing in the same area.
2016-02-07 22:02:44 +01:00
columns of a table can contain only unique (non-duplicate), nonnull
values. Only one primary key can be specified for a table, whether as a
column constraint or a table constraint.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Improve documentation about PRIMARY KEY constraints. Get rid of the false implication that PRIMARY KEY is exactly equivalent to UNIQUE + NOT NULL. That was more-or-less true at one time in our implementation, but the standard doesn't say that, and we've grown various features (many of them required by spec) that treat a pkey differently from less-formal constraints. Per recent discussion on pgsql-general. I failed to resist the temptation to do some other wordsmithing in the same area.
2016-02-07 22:02:44 +01:00
The primary key constraint should name a set of columns that is
different from the set of columns named by any unique
constraint defined for the same table. (Otherwise, the unique
constraint is redundant and will be discarded.)
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Editing and markup cleanup.
1998-09-22 17:48:03 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Improve documentation about PRIMARY KEY constraints. Get rid of the false implication that PRIMARY KEY is exactly equivalent to UNIQUE + NOT NULL. That was more-or-less true at one time in our implementation, but the standard doesn't say that, and we've grown various features (many of them required by spec) that treat a pkey differently from less-formal constraints. Per recent discussion on pgsql-general. I failed to resist the temptation to do some other wordsmithing in the same area.
2016-02-07 22:02:44 +01:00
<literal>PRIMARY KEY</literal> enforces the same data constraints as
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
a combination of <literal>UNIQUE</literal> and <literal>NOT
NULL</literal>. However,
Improve documentation about PRIMARY KEY constraints. Get rid of the false implication that PRIMARY KEY is exactly equivalent to UNIQUE + NOT NULL. That was more-or-less true at one time in our implementation, but the standard doesn't say that, and we've grown various features (many of them required by spec) that treat a pkey differently from less-formal constraints. Per recent discussion on pgsql-general. I failed to resist the temptation to do some other wordsmithing in the same area.
2016-02-07 22:02:44 +01:00
identifying a set of columns as the primary key also provides metadata
about the design of the schema, since a primary key implies that other
tables can rely on this set of columns as a unique identifier for rows.
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
<para>
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
When placed on a partitioned table, <literal>PRIMARY KEY</literal>
Fix typo Author: Daniel Gustafsson <daniel@yesql.se> Discussion: https://postgr.es/m/0CF087FC-BEAD-4010-8BB9-3CDD74DC9060@yesql.se
2021-02-17 13:53:26 +01:00
constraints share the restrictions previously described
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
for <literal>UNIQUE</literal> constraints.
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
</para>
Indexes with INCLUDE columns and their support in B-tree This patch introduces INCLUDE clause to index definition. This clause specifies a list of columns which will be included as a non-key part in the index. The INCLUDE columns exist solely to allow more queries to benefit from index-only scans. Also, such columns don't need to have appropriate operator classes. Expressions are not supported as INCLUDE columns since they cannot be used in index-only scans. Index access methods supporting INCLUDE are indicated by amcaninclude flag in IndexAmRoutine. For now, only B-tree indexes support INCLUDE clause. In B-tree indexes INCLUDE columns are truncated from pivot index tuples (tuples located in non-leaf pages and high keys). Therefore, B-tree indexes now might have variable number of attributes. This patch also provides generic facility to support that: pivot tuples contain number of their attributes in t_tid.ip_posid. Free 13th bit of t_info is used for indicating that. This facility will simplify further support of index suffix truncation. The changes of above are backward-compatible, pg_upgrade doesn't need special handling of B-tree indexes for that. Bump catalog version Author: Anastasia Lubennikova with contribition by Alexander Korotkov and me Reviewed by: Peter Geoghegan, Tomas Vondra, Antonin Houska, Jeff Janes, David Rowley, Alexander Korotkov Discussion: https://www.postgresql.org/message-id/flat/56168952.4010101@postgrespro.ru
2018-04-07 22:00:39 +02:00
<para>
Add temporal PRIMARY KEY and UNIQUE constraints Add WITHOUT OVERLAPS clause to PRIMARY KEY and UNIQUE constraints. These are backed by GiST indexes instead of B-tree indexes, since they are essentially exclusion constraints with = for the scalar parts of the key and && for the temporal part. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-01-24 15:43:41 +01:00
As with a <literal>UNIQUE</literal> constraint, adding a
<literal>PRIMARY KEY</literal> constraint will automatically create a
unique B-tree index, or GiST if <literal>WITHOUT OVERLAPS</literal> was
specified, on the column or group of columns used in the constraint.
doc: Document more that relations share a namespace This was already documented in the CREATE INDEX reference, but not in the introductory "Data Definition" chapter. Also, document that the index that implements a constraint has the same name as the constraint. Author: Laurenz Albe <laurenz.albe@cybertec.at> Reviewed-by: jian he <jian.universality@gmail.com> Reviewed-by: David G. Johnston <david.g.johnston@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CACJufxFG682tYcP9aH_F-jrqq5End8MHZR77zcp1%3DDUrEsSu1Q%40mail.gmail.com
2024-01-31 11:53:56 +01:00
That index has the same name as the primary key constraint.
Doc: clarify that CREATE TABLE discards redundant unique constraints. The SQL standard says that redundant unique constraints are disallowed, but we long ago decided that throwing an error would be too user-unfriendly, so we just drop redundant ones. The docs weren't very clear about that though, as this behavior was only explained for PRIMARY KEY vs UNIQUE, not UNIQUE vs UNIQUE. While here, I couldn't resist doing some copy-editing and markup-fixing on the adjacent text about INCLUDE options. Per bug #16767 from Matthias vd Meent. Discussion: https://postgr.es/m/16767-1714a2056ca516d0@postgresql.org
2020-12-08 19:09:47 +01:00
</para>
<para>
The optional <literal>INCLUDE</literal> clause adds to that index
one or more columns that are simply <quote>payload</quote>: uniqueness
is not enforced on them, and the index cannot be searched on the basis
of those columns. However they can be retrieved by an index-only scan.
Note that although the constraint is not enforced on included columns,
it still depends on them. Consequently, some operations on such columns
(e.g., <literal>DROP COLUMN</literal>) can cause cascaded constraint and
index deletion.
Indexes with INCLUDE columns and their support in B-tree This patch introduces INCLUDE clause to index definition. This clause specifies a list of columns which will be included as a non-key part in the index. The INCLUDE columns exist solely to allow more queries to benefit from index-only scans. Also, such columns don't need to have appropriate operator classes. Expressions are not supported as INCLUDE columns since they cannot be used in index-only scans. Index access methods supporting INCLUDE are indicated by amcaninclude flag in IndexAmRoutine. For now, only B-tree indexes support INCLUDE clause. In B-tree indexes INCLUDE columns are truncated from pivot index tuples (tuples located in non-leaf pages and high keys). Therefore, B-tree indexes now might have variable number of attributes. This patch also provides generic facility to support that: pivot tuples contain number of their attributes in t_tid.ip_posid. Free 13th bit of t_info is used for indicating that. This facility will simplify further support of index suffix truncation. The changes of above are backward-compatible, pg_upgrade doesn't need special handling of B-tree indexes for that. Bump catalog version Author: Anastasia Lubennikova with contribition by Alexander Korotkov and me Reviewed by: Peter Geoghegan, Tomas Vondra, Antonin Houska, Jeff Janes, David Rowley, Alexander Korotkov Discussion: https://www.postgresql.org/message-id/flat/56168952.4010101@postgrespro.ru
2018-04-07 22:00:39 +02:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
Editing and markup cleanup.
1998-09-22 17:48:03 +02:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<varlistentry id="sql-createtable-exclude">
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
<term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ]</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>EXCLUDE</literal> clause defines an exclusion
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
constraint, which guarantees that if
any two rows are compared on the specified column(s) or
expression(s) using the specified operator(s), not all of these
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
comparisons will return <literal>TRUE</literal>. If all of the
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
specified operators test for equality, this is equivalent to a
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>UNIQUE</literal> constraint, although an ordinary unique constraint
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
will be faster. However, exclusion constraints can specify
constraints that are more general than simple equality.
For example, you can specify a constraint that
no two rows in the table contain overlapping circles
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="datatype-geometric"/>) by using the
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>&amp;&amp;</literal> operator.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Editing and markup cleanup.
1998-09-22 17:48:03 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Exclusion constraints are implemented using
doc: Document more that relations share a namespace This was already documented in the CREATE INDEX reference, but not in the introductory "Data Definition" chapter. Also, document that the index that implements a constraint has the same name as the constraint. Author: Laurenz Albe <laurenz.albe@cybertec.at> Reviewed-by: jian he <jian.universality@gmail.com> Reviewed-by: David G. Johnston <david.g.johnston@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CACJufxFG682tYcP9aH_F-jrqq5End8MHZR77zcp1%3DDUrEsSu1Q%40mail.gmail.com
2024-01-31 11:53:56 +01:00
an index that has the same name as the constraint, so each specified
operator must be associated with an appropriate operator class
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="indexes-opclass"/>) for the index access
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
method <replaceable>index_method</replaceable>.
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
The operators are required to be commutative.
Each <replaceable class="parameter">exclude_element</replaceable>
can optionally specify an operator class and/or ordering options;
these are described fully under
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createindex"/>.
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The access method must support <literal>amgettuple</literal> (see <xref
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
linkend="indexam"/>); at present this means <acronym>GIN</acronym>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
cannot be used. Although it's allowed, there is little point in using
Spell and markup checking
2010-08-17 06:37:21 +02:00
B-tree or hash indexes with an exclusion constraint, because this
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
does nothing that an ordinary unique constraint doesn't do better.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
So in practice the access method will always be <acronym>GiST</acronym> or
<acronym>SP-GiST</acronym>.
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <replaceable class="parameter">predicate</replaceable> allows you to specify an
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
exclusion constraint on a subset of the table; internally this creates a
partial index. Note that parentheses are required around the predicate.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references">
Clarify referential actions in docs of CREATE/ALTER TABLE The documentation of ON DELETE and ON UPDATE uses the term "action", which is also used on the ALTER TABLE page for other purposes. This commit renames the term to "referential_action", which is more consistent with the SQL specification. The new term is now used on the documentation of both CREATE TABLE and ALTER TABLE for consistency. Reported-by: Brigitte Blanc-Lafay Author: Lætitia Avrot Reviewed-by: Álvaro Herrera Discussion: https://postgr.es/m/CAB_COdiHEVVs0uB+uYCjjYUwQ4YFFekppq+Xqv6qAM8+cd42gA@mail.gmail.com
2018-12-28 02:19:14 +01:00
<term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">referential_action</replaceable> ] [ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal> (column constraint)</term>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
<term><literal>FOREIGN KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] )
REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] [, PERIOD <replaceable class="parameter">column_name</replaceable> ] ) ]
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
[ MATCH <replaceable class="parameter">matchtype</replaceable> ]
Clarify referential actions in docs of CREATE/ALTER TABLE The documentation of ON DELETE and ON UPDATE uses the term "action", which is also used on the ALTER TABLE page for other purposes. This commit renames the term to "referential_action", which is more consistent with the SQL specification. The new term is now used on the documentation of both CREATE TABLE and ALTER TABLE for consistency. Reported-by: Brigitte Blanc-Lafay Author: Lætitia Avrot Reviewed-by: Álvaro Herrera Discussion: https://postgr.es/m/CAB_COdiHEVVs0uB+uYCjjYUwQ4YFFekppq+Xqv6qAM8+cd42gA@mail.gmail.com
2018-12-28 02:19:14 +01:00
[ ON DELETE <replaceable class="parameter">referential_action</replaceable> ]
[ ON UPDATE <replaceable class="parameter">referential_action</replaceable> ]</literal>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
(table constraint)</term>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
These clauses specify a foreign key constraint, which requires
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
that a group of one or more columns of the new table must only
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
contain values that match values in the referenced
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
column(s) of some row of the referenced table. If the <replaceable
class="parameter">refcolumn</replaceable> list is omitted, the
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
primary key of the <replaceable class="parameter">reftable</replaceable>
Doc: mention foreign keys can reference unique indexes We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-29 22:15:17 +01:00
is used. Otherwise, the <replaceable class="parameter">refcolumn</replaceable>
list must refer to the columns of a non-deferrable unique or primary key
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
constraint or be the columns of a non-partial unique index.
</para>
<para>
If the last column is marked with <literal>PERIOD</literal>, it is
treated in a special way. While the non-<literal>PERIOD</literal>
columns are compared for equality (and there must be at least one of
them), the <literal>PERIOD</literal> column is not. Instead, the
constraint is considered satisfied if the referenced table has matching
records (based on the non-<literal>PERIOD</literal> parts of the key)
whose combined <literal>PERIOD</literal> values completely cover the
referencing record's. In other words, the reference must have a
referent for its entire duration. This column must be a range or
multirange type. In addition, the referenced table must have a primary
key or unique constraint declared with <literal>WITHOUT
OVERLAPS</literal>. Finally, if one side of the foreign key uses
<literal>PERIOD</literal>, the other side must too. If the <replaceable
class="parameter">refcolumn</replaceable> list is omitted, the
<literal>WITHOUT OVERLAPS</literal> part of the primary key is treated
as if marked with <literal>PERIOD</literal>.
</para>
<para>
The user
Doc: mention foreign keys can reference unique indexes We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-29 22:15:17 +01:00
must have <literal>REFERENCES</literal> permission on the referenced
table (either the whole table, or the specific referenced columns). The
Document lock taken on referenced table when adding a foreign key This can happen for CREATE TABLE and ALTER TABLE, so a mention is added to both of them in the concerned subsections. Author: Adrien Nayrat Discussion: https://postgr.es/m/c4e8af11-1dfc-766a-c953-76979b9fcdaa@anayrat.info
2018-09-21 08:03:37 +02:00
addition of a foreign key constraint requires a
<literal>SHARE ROW EXCLUSIVE</literal> lock on the referenced table.
For foreign keys, check REFERENCES privilege only on the referenced table. We were requiring that the user have REFERENCES permission on both the referenced and referencing tables --- but this doesn't seem to have any support in the SQL standard, which says only that you need REFERENCES permission on the referenced table. And ALTER TABLE ADD FOREIGN KEY has already checked that you own the referencing table, so the check could only fail if a table owner has revoked his own REFERENCES permission. Moreover, the symmetric interpretation of this permission is unintuitive and confusing, as per complaint from Paul Jungwirth. So let's drop the referencing-side check. In passing, do a bit of wordsmithing on the GRANT reference page so that all the privilege types are described in similar fashion. Discussion: https://postgr.es/m/8940.1490906755@sss.pgh.pa.us
2017-04-01 00:11:25 +02:00
Note that foreign key constraints cannot be defined between temporary
Support foreign keys that reference partitioned tables Previously, while primary keys could be made on partitioned tables, it was not possible to define foreign keys that reference those primary keys. Now it is possible to do that. Author: Álvaro Herrera Reviewed-by: Amit Langote, Jesper Pedersen Discussion: https://postgr.es/m/20181102234158.735b3fevta63msbj@alvherre.pgsql
2019-04-03 19:38:20 +02:00
tables and permanent tables.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
A value inserted into the referencing column(s) is matched against the
More editing of reference pages.
2003-04-22 12:08:08 +02:00
values of the referenced table and referenced columns using the
given match type. There are three match types: <literal>MATCH
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
FULL</literal>, <literal>MATCH PARTIAL</literal>, and <literal>MATCH
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
SIMPLE</literal> (which is the default). <literal>MATCH
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
FULL</literal> will not allow one column of a multicolumn foreign key
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
to be null unless all foreign key columns are null; if they are all
null, the row is not required to have a match in the referenced table.
<literal>MATCH SIMPLE</literal> allows any of the foreign key columns
to be null; if any of them are null, the row is not required to have a
match in the referenced table.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>MATCH PARTIAL</literal> is not yet implemented.
(Of course, <literal>NOT NULL</literal> constraints can be applied to the
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
referencing column(s) to prevent these cases from arising.)
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
In addition, when the data in the referenced columns is changed,
certain actions are performed on the data in this table's
columns. The <literal>ON DELETE</literal> clause specifies the
More editing of reference pages.
2003-04-22 12:08:08 +02:00
action to perform when a referenced row in the referenced table is
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
being deleted. Likewise, the <literal>ON UPDATE</literal>
clause specifies the action to perform when a referenced column
in the referenced table is being updated to a new value. If the
row is updated, but the referenced column is not actually
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
changed, no action is done. Referential actions other than the
<literal>NO ACTION</literal> check cannot be deferred, even if
the constraint is declared deferrable. There are the following possible
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
actions for each clause:
<variablelist>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references-refact-no-action">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<term><literal>NO ACTION</literal></term>
<listitem>
<para>
Produce an error indicating that the deletion or update
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
would create a foreign key constraint violation.
If the constraint is deferred, this
error will be produced at constraint check time if there still
exist any referencing rows. This is the default action.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references-refact-restrict">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
Produce an error indicating that the deletion or update
would create a foreign key constraint violation.
This is the same as <literal>NO ACTION</literal> except that
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
the check is not deferrable.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references-refact-cascade">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Delete any rows referencing the deleted row, or update the
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
values of the referencing column(s) to the new values of the
referenced columns, respectively.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
<para>
In a temporal foreign key, this option is not supported.
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references-refact-set-null">
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
<term><literal>SET NULL [ ( <replaceable>column_name</replaceable> [, ... ] ) ]</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
Set all of the referencing columns, or a specified subset of the
referencing columns, to null. A subset of columns can only be
specified for <literal>ON DELETE</literal> actions.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
<para>
In a temporal foreign key, this option is not supported.
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-references-refact-set-default">
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
<term><literal>SET DEFAULT [ ( <replaceable>column_name</replaceable> [, ... ] ) ]</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
Set all of the referencing columns, or a specified subset of the
referencing columns, to their default values. A subset of columns
can only be specified for <literal>ON DELETE</literal> actions.
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
(There must be a row in the referenced table matching the default
values, if they are not null, or the operation will fail.)
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
Add temporal FOREIGN KEY contraints Add PERIOD clause to foreign key constraint definitions. This is supported for range and multirange types. Temporal foreign keys check for range containment instead of equality. This feature matches the behavior of the SQL standard temporal foreign keys, but it works on PostgreSQL's native ranges instead of SQL's "periods", which don't exist in PostgreSQL (yet). Reference actions ON {UPDATE,DELETE} {CASCADE,SET NULL,SET DEFAULT} are not supported yet. Author: Paul A. Jungwirth <pj@illuminatedcomputing.com> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: jian he <jian.universality@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/CA+renyUApHgSZF9-nd-a0+OPGharLQLO=mDHcY4_qQ0+noCUVg@mail.gmail.com
2024-03-24 07:37:13 +01:00
<para>
In a temporal foreign key, this option is not supported.
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
</variablelist>
</para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
Add mention of index on foreign key for frequently updated primary key tables.
2002-01-03 07:26:22 +01:00
<para>
Update reference 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".
2007-02-01 00:26:05 +01:00
If the referenced column(s) are changed frequently, it might be wise to
Change ON UPDATE SET NULL/SET DEFAULT referential actions to meet SQL spec. Previously, when executing an ON UPDATE SET NULL or SET DEFAULT action for a multicolumn MATCH SIMPLE foreign key constraint, we would set only those referencing columns corresponding to referenced columns that were changed. This is what the SQL92 standard said to do --- but more recent versions of the standard say that all referencing columns should be set to null or their default values, no matter exactly which referenced columns changed. At least for SET DEFAULT, that is clearly saner behavior. It's somewhat debatable whether it's an improvement for SET NULL, but it appears that other RDBMS systems read the spec this way. So let's do it like that. This is a release-notable behavioral change, although considering that our documentation already implied it was done this way, the lack of complaints suggests few people use such cases.
2012-06-18 18:12:52 +02:00
add an index to the referencing column(s) so that referential actions
associated with the foreign key constraint can be performed more
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
efficiently.
Add mention of index on foreign key for frequently updated primary key tables.
2002-01-03 07:26:22 +01:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</listitem>
</varlistentry>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-deferrable">
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<term><literal>DEFERRABLE</literal></term>
<term><literal>NOT DEFERRABLE</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
This controls whether the constraint can be deferred. A
constraint that is not deferrable will be checked immediately
after every command. Checking of constraints that are
Update reference 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".
2007-02-01 00:26:05 +01:00
deferrable can be postponed until the end of the transaction
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
(using the <link linkend="sql-set-constraints"><command>SET CONSTRAINTS</command></link> command).
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
<literal>NOT DEFERRABLE</literal> is the default.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Currently, only <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>,
<literal>EXCLUDE</literal>, and
<literal>REFERENCES</literal> (foreign key) constraints accept this
clause. <literal>NOT NULL</literal> and <literal>CHECK</literal> constraints are not
Add support for INSERT ... ON CONFLICT DO NOTHING/UPDATE. The newly added ON CONFLICT clause allows to specify an alternative to raising a unique or exclusion constraint violation error when inserting. ON CONFLICT refers to constraints that can either be specified using a inference clause (by specifying the columns of a unique constraint) or by naming a unique or exclusion constraint. DO NOTHING avoids the constraint violation, without touching the pre-existing row. DO UPDATE SET ... [WHERE ...] updates the pre-existing tuple, and has access to both the tuple proposed for insertion and the existing tuple; the optional WHERE clause can be used to prevent an update from being executed. The UPDATE SET and WHERE clauses have access to the tuple proposed for insertion using the "magic" EXCLUDED alias, and to the pre-existing tuple using the table name or its alias. This feature is often referred to as upsert. This is implemented using a new infrastructure called "speculative insertion". It is an optimistic variant of regular insertion that first does a pre-check for existing tuples and then attempts an insert. If a violating tuple was inserted concurrently, the speculatively inserted tuple is deleted and a new attempt is made. If the pre-check finds a matching tuple the alternative DO NOTHING or DO UPDATE action is taken. If the insertion succeeds without detecting a conflict, the tuple is deemed inserted. To handle the possible ambiguity between the excluded alias and a table named excluded, and for convenience with long relation names, INSERT INTO now can alias its target table. Bumps catversion as stored rules change. Author: Peter Geoghegan, with significant contributions from Heikki Linnakangas and Andres Freund. Testing infrastructure by Jeff Janes. Reviewed-By: Heikki Linnakangas, Andres Freund, Robert Haas, Simon Riggs, Dean Rasheed, Stephen Frost and many others.
2015-05-08 05:31:36 +02:00
deferrable. Note that deferrable constraints cannot be used as
conflict arbitrators in an <command>INSERT</command> statement that
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
includes an <literal>ON CONFLICT DO UPDATE</literal> clause.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-initially">
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<term><literal>INITIALLY IMMEDIATE</literal></term>
<term><literal>INITIALLY DEFERRED</literal></term>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<listitem>
<para>
If a constraint is deferrable, this clause specifies the default
time to check the constraint. If the constraint is
<literal>INITIALLY IMMEDIATE</literal>, it is checked after each
statement. This is the default. If the constraint is
<literal>INITIALLY DEFERRED</literal>, it is checked only at the
end of the transaction. The constraint check time can be
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
altered with the <link linkend="sql-set-constraints"><command>SET CONSTRAINTS</command></link> command.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</listitem>
</varlistentry>
Add mention of index on foreign key for frequently updated primary key tables.
2002-01-03 07:26:22 +01:00
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
<varlistentry id="sql-createtable-method">
<term><literal>USING <replaceable class="parameter">method</replaceable></literal></term>
<listitem>
<para>
This optional clause specifies the table access method to use to store
the contents for the new table; the method needs be an access method of
type <literal>TABLE</literal>. See <xref linkend="tableam"/> for more
information. If this option is not specified, the default table access
Fix copy-and-paste mistakes in documentation. Reported-by: Vik Fearing
2019-05-08 11:14:14 +02:00
method is chosen for the new table. See <xref
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
linkend="guc-default-table-access-method"/> for more information.
</para>
Allow specifying an access method for partitioned tables It's now possible to specify a table access method via CREATE TABLE ... USING for a partitioned table, as well change it with ALTER TABLE ... SET ACCESS METHOD. Specifying an AM for a partitioned table lets the value be used for all future partitions created under it, closely mirroring the behavior of the TABLESPACE option for partitioned tables. Existing partitions are not modified. For a partitioned table with no AM specified, any new partitions are created with the default_table_access_method. Also add ALTER TABLE ... SET ACCESS METHOD DEFAULT, which reverts to the original state of using the default for new partitions. The relcache of partitioned tables is not changed: rd_tableam is not set, even if a partitioned table has a relam set. Author: Justin Pryzby <pryzby@telsasoft.com> Author: Soumyadeep Chakraborty <soumyadeep2007@gmail.com> Author: Michaël Paquier <michael@paquier.xyz> Reviewed-by: The authors themselves Discussion: https://postgr.es/m/CAE-ML+9zM4wJCGCBGv01k96qQ3gFv4WFcFy=zqPHKeaEFwwv6A@mail.gmail.com Discussion: https://postgr.es/m/20210308010707.GA29832%40telsasoft.com
2024-03-25 16:30:36 +01:00
<para>
When creating a partition, the table access method is the access method
of its partitioned table, if set.
</para>
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-with">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
This clause specifies optional storage parameters for a table or index;
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs. Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
2020-05-11 20:15:49 +02:00
see <xref linkend="sql-createtable-storage-parameters"/> below for more
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
information. For backward-compatibility the <literal>WITH</literal>
clause for a table can also include <literal>OIDS=FALSE</literal> to
specify that rows of the new table should not contain OIDs (object
identifiers), <literal>OIDS=TRUE</literal> is not supported anymore.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-without-oids">
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><literal>WITHOUT OIDS</literal></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
This is backward-compatible syntax for declaring a table
<literal>WITHOUT OIDS</literal>, creating a table <literal>WITH
OIDS</literal> is not supported anymore.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-on-commit">
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
<term><literal>ON COMMIT</literal></term>
<listitem>
<para>
Code review for ON COMMIT patch. Make the actual on-commit action happen before commit, not after :-( --- the original coding is not only unsafe if an error occurs while it's processing, but it generates an invalid sequence of WAL entries. Resurrect 7.2 logic for deleting items when no longer needed. Use an enum instead of random macros. Editorialize on names used for routines and constants. Teach backend/nodes routines about new field in CreateTable struct. Add a regression test.
2002-11-11 23:19:25 +01:00
The behavior of temporary tables at the end of a transaction
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
block can be controlled using <literal>ON COMMIT</literal>.
Code review for ON COMMIT patch. Make the actual on-commit action happen before commit, not after :-( --- the original coding is not only unsafe if an error occurs while it's processing, but it generates an invalid sequence of WAL entries. Resurrect 7.2 logic for deleting items when no longer needed. Use an enum instead of random macros. Editorialize on names used for routines and constants. Teach backend/nodes routines about new field in CreateTable struct. Add a regression test.
2002-11-11 23:19:25 +01:00
The three options are:
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
<variablelist>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-on-commit-preserve-rows">
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
<term><literal>PRESERVE ROWS</literal></term>
<listitem>
<para>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
No special action is taken at the ends of transactions.
This is the default behavior.
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</para>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
</listitem>
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</varlistentry>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-on-commit-delete-rows">
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
<term><literal>DELETE ROWS</literal></term>
<listitem>
<para>
Add TABLESPACE and ON COMMIT clauses to CREATE TABLE AS. ON COMMIT is required by the SQL standard, and TABLESPACE is useful functionality. Patch from Kris Jurka, minor editorialization by Neil Conway.
2006-02-19 01:04:28 +01:00
All rows in the temporary table will be deleted at the end
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
of each transaction block. Essentially, an automatic <link
linkend="sql-truncate"><command>TRUNCATE</command></link> is done
Fix dependency handling of partitions and inheritance for ON COMMIT This commit fixes a set of issues with ON COMMIT actions when used on partitioned tables and tables with inheritance children: - Applying ON COMMIT DROP on a partitioned table with partitions or on a table with inheritance children caused a failure at commit time, with complains about the children being already dropped as all relations are dropped one at the same time. - Applying ON COMMIT DELETE on a partition relying on a partitioned table which uses ON COMMIT DROP would cause the partition truncation to fail as the parent is removed first. The solution to the first problem is to handle the removal of all the dependencies in one go instead of dropping relations one-by-one, based on a suggestion from Álvaro Herrera. So instead all the relation OIDs to remove are gathered and then processed in one round of multiple deletions. The solution to the second problem is to reorder the actions, with truncation happening first and relation drop done after. Even if it means that a partition could be first truncated, then immediately dropped if its partitioned table is dropped, this has the merit to keep the code simple as there is no need to do existence checks on the relations to drop. Contrary to a manual TRUNCATE on a partitioned table, ON COMMIT DELETE does not cascade to its partitions. The ON COMMIT action defined on each partition gets the priority. Author: Michael Paquier Reviewed-by: Amit Langote, Álvaro Herrera, Robert Haas Discussion: https://postgr.es/m/68f17907-ec98-1192-f99f-8011400517f5@lab.ntt.co.jp Backpatch-through: 10
2018-11-09 02:03:22 +01:00
at each commit. When used on a partitioned table, this
is not cascaded to its partitions.
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</para>
</listitem>
</varlistentry>
Add mention of index on foreign key for frequently updated primary key tables.
2002-01-03 07:26:22 +01:00
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-on-commit-drop">
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
<term><literal>DROP</literal></term>
<listitem>
<para>
Code review for ON COMMIT patch. Make the actual on-commit action happen before commit, not after :-( --- the original coding is not only unsafe if an error occurs while it's processing, but it generates an invalid sequence of WAL entries. Resurrect 7.2 logic for deleting items when no longer needed. Use an enum instead of random macros. Editorialize on names used for routines and constants. Teach backend/nodes routines about new field in CreateTable struct. Add a regression test.
2002-11-11 23:19:25 +01:00
The temporary table will be dropped at the end of the current
Fix dependency handling of partitions and inheritance for ON COMMIT This commit fixes a set of issues with ON COMMIT actions when used on partitioned tables and tables with inheritance children: - Applying ON COMMIT DROP on a partitioned table with partitions or on a table with inheritance children caused a failure at commit time, with complains about the children being already dropped as all relations are dropped one at the same time. - Applying ON COMMIT DELETE on a partition relying on a partitioned table which uses ON COMMIT DROP would cause the partition truncation to fail as the parent is removed first. The solution to the first problem is to handle the removal of all the dependencies in one go instead of dropping relations one-by-one, based on a suggestion from Álvaro Herrera. So instead all the relation OIDs to remove are gathered and then processed in one round of multiple deletions. The solution to the second problem is to reorder the actions, with truncation happening first and relation drop done after. Even if it means that a partition could be first truncated, then immediately dropped if its partitioned table is dropped, this has the merit to keep the code simple as there is no need to do existence checks on the relations to drop. Contrary to a manual TRUNCATE on a partitioned table, ON COMMIT DELETE does not cascade to its partitions. The ON COMMIT action defined on each partition gets the priority. Author: Michael Paquier Reviewed-by: Amit Langote, Álvaro Herrera, Robert Haas Discussion: https://postgr.es/m/68f17907-ec98-1192-f99f-8011400517f5@lab.ntt.co.jp Backpatch-through: 10
2018-11-09 02:03:22 +01:00
transaction block. When used on a partitioned table, this action
drops its partitions and when used on tables with inheritance
children, it drops the dependent children.
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</para>
</listitem>
</varlistentry>
Fix a whitespace issue with the man pages There is what may actually be a mistake in our markup. The problem is in a situation like <para> <command>FOO</command> is ... there is strictly speaking a line break before "FOO". In the HTML output, this does not appear to be a problem, but in the man page output, this shows up, so you get double blank lines at odd places. So far, we have attempted to work around this with an XSL hack, but that causes other problems, such as creating run-ins in places like <acronym>SQL</acronym> <command>COPY</command> So fix the problem properly by removing the extra whitespace. I only fixed the problems that affect the man page output, not all the places.
2011-08-07 09:49:45 +02:00
</variablelist></para>
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</listitem>
</varlistentry>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
tableam: basic documentation. This adds documentation about the user oriented parts of table access methods (i.e. the default_table_access_method GUC and the USING clause for CREATE TABLE etc), adds a basic chapter about the table access method interface, and adds a note to storage.sgml that it's contents don't necessarily apply for non-builtin AMs. Author: Haribabu Kommi and Andres Freund Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de
2019-04-04 02:37:00 +02:00
<varlistentry id="sql-createtable-tablespace">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>TABLESPACE <replaceable class="parameter">tablespace_name</replaceable></literal></term>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
<listitem>
<para>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
The <replaceable class="parameter">tablespace_name</replaceable> is the name
Create 'default_tablespace' GUC variable that supplies a TABLESPACE clause implicitly whenever one is not given explicitly. Remove concept of a schema having an associated tablespace, and simplify the rules for selecting a default tablespace for a table or index. It's now just (a) explicit TABLESPACE clause; (b) default_tablespace if that's not an empty string; (c) database's default. This will allow pg_dump to use SET commands instead of tablespace clauses to determine object locations (but I didn't actually make it do so). All per recent discussions.
2004-11-05 20:17:13 +01:00
of the tablespace in which the new table is to be created.
If not specified,
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="guc-default-tablespace"/> is consulted, or
Fix tablespace handling for partitioned tables When partitioned tables were introduced, we failed to realize that by copying the tablespace handling for other relation kinds with no physical storage we were causing the secondary effect that their partitions would not automatically inherit the tablespace setting. This is surprising and unhelpful, so change it to adopt the behavior introduced in pg11 (commit 33e6c34c3267) for partitioned indexes: the parent relation remembers the tablespace specification, which is then used for any new partitions that don't declare one. Because this commit changes behavior of the TABLESPACE clause for partitioned tables (it's no longer a no-op), it is not backpatched. Author: David Rowley, Álvaro Herrera Reviewed-by: Michael Paquier Discussion: https://postgr.es/m/CAKJS1f9SxVzqDrGD1teosFd6jBMM0UEaa14_8mRvcWE19Tu0hA@mail.gmail.com
2018-12-17 19:37:40 +01:00
<xref linkend="guc-temp-tablespaces"/> if the table is temporary. For
partitioned tables, since no storage is required for the table itself,
Fix tablespace inheritance for partitioned rels Commit ca4103025dfe left a few loose ends. The most important one (broken pg_dump output) is already fixed by virtue of commit 3b23552ad8bb, but some things remained: * When ALTER TABLE rewrites tables, the indexes must remain in the tablespace they were originally in. This didn't work because index recreation during ALTER TABLE runs manufactured SQL (yuck), which runs afoul of default_tablespace in competition with the parent relation tablespace. To fix, reset default_tablespace to the empty string temporarily, and add the TABLESPACE clause as appropriate. * Setting a partitioned rel's tablespace to the database default is confusing; if it worked, it would direct the partitions to that tablespace regardless of default_tablespace. But in reality it does not work, and making it work is a larger project. Therefore, throw an error when this condition is detected, to alert the unwary. Add some docs and tests, too. Author: Álvaro Herrera Discussion: https://postgr.es/m/CAKJS1f_1c260nOt_vBJ067AZ3JXptXVRohDVMLEBmudX1YEx-A@mail.gmail.com
2019-04-25 16:20:23 +02:00
the tablespace specified overrides <literal>default_tablespace</literal>
as the default tablespace to use for any newly created partitions when no
other tablespace is explicitly specified.
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
</para>
</listitem>
</varlistentry>
Doc: add XML ID attributes to <sectN> and <varlistentry> tags. This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
2023-01-09 21:08:24 +01:00
<varlistentry id="sql-createtable-parms-using-index-tablespace">
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>USING INDEX TABLESPACE <replaceable class="parameter">tablespace_name</replaceable></literal></term>
Support USING INDEX TABLESPACE clause for PRIMARY KEY and UNIQUE constraints. Christopher Kings-Lynne.
2004-08-02 06:28:29 +02:00
<listitem>
<para>
This clause allows selection of the tablespace in which the index
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
associated with a <literal>UNIQUE</literal>, <literal>PRIMARY
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
KEY</literal>, or <literal>EXCLUDE</literal> constraint will be created.
Create 'default_tablespace' GUC variable that supplies a TABLESPACE clause implicitly whenever one is not given explicitly. Remove concept of a schema having an associated tablespace, and simplify the rules for selecting a default tablespace for a table or index. It's now just (a) explicit TABLESPACE clause; (b) default_tablespace if that's not an empty string; (c) database's default. This will allow pg_dump to use SET commands instead of tablespace clauses to determine object locations (but I didn't actually make it do so). All per recent discussions.
2004-11-05 20:17:13 +01:00
If not specified,
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="guc-default-tablespace"/> is consulted, or
<xref linkend="guc-temp-tablespaces"/> if the table is temporary.
Support USING INDEX TABLESPACE clause for PRIMARY KEY and UNIQUE constraints. Christopher Kings-Lynne.
2004-08-02 06:28:29 +02:00
</para>
</listitem>
</varlistentry>
Add code to handle [ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }] for temp tables. Gavin Sherry
2002-11-10 00:56:39 +01:00
</variablelist>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs. Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
2020-05-11 20:15:49 +02:00
<refsect2 id="sql-createtable-storage-parameters" xreflabel="Storage Parameters">
<title>Storage Parameters</title>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<indexterm zone="sql-createtable-storage-parameters">
<primary>storage parameters</primary>
</indexterm>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>WITH</literal> clause can specify <firstterm>storage parameters</firstterm>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
for tables, and for indexes associated with a <literal>UNIQUE</literal>,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</literal> constraint.
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
Storage parameters for
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
indexes are documented in <xref linkend="sql-createindex"/>.
Use "TOAST table" in place of the vague, not-used-elsewhere phrase "supplementary storage table".
2010-05-13 20:54:18 +02:00
The storage parameters currently
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
available for tables are listed below. For many of these parameters, as
shown, there is an additional parameter with the same name prefixed with
<literal>toast.</literal>, which controls the behavior of the
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
table's secondary <acronym>TOAST</acronym> table, if any
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="storage-toast"/> for more information about TOAST).
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
If a table parameter value is set and the
equivalent <literal>toast.</literal> parameter is not, the TOAST table
will use the table's parameter value.
Revert analyze support for partitioned tables This reverts the following commits: 1b5617eb844cd2470a334c1d2eec66cf9b39c41a Describe (auto-)analyze behavior for partitioned tables 0e69f705cc1a3df273b38c9883fb5765991e04fe Set pg_class.reltuples for partitioned tables 41badeaba8beee7648ebe7923a41c04f1f3cb302 Document ANALYZE storage parameters for partitioned tables 0827e8af70f4653ba17ed773f123a60eadd9f9c9 autovacuum: handle analyze for partitioned tables There are efficiency issues in this code when handling databases with large numbers of partitions, and it doesn't look like there isn't any trivial way to handle those. There are some other issues as well. It's now too late in the cycle for nontrivial fixes, so we'll have to let Postgres 14 users continue to manually deal with ANALYZE their partitioned tables, and hopefully we can fix the issues for Postgres 15. I kept [most of] be280cdad298 ("Don't reset relhasindex for partitioned tables on ANALYZE") because while we added it due to 0827e8af70f4, it is a good bugfix in its own right, since it affects manual analyze as well as autovacuum-induced analyze, and there's no reason to revert it. I retained the addition of relkind 'p' to tables included by pg_stat_user_tables, because reverting that would require a catversion bump. Also, in pg14 only, I keep a struct member that was added to PgStat_TabStatEntry to avoid breaking compatibility with existing stat files. Backpatch to 14. Discussion: https://postgr.es/m/20210722205458.f2bug3z6qzxzpx2s@alap3.anarazel.de
2021-08-16 23:27:52 +02:00
Specifying these parameters for partitioned tables is not supported,
but you may specify them for individual leaf partitions.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
<variablelist>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-fillfactor" xreflabel="fillfactor">
<term><varname>fillfactor</varname> (<type>integer</type>)
<indexterm>
<primary><varname>fillfactor</varname> storage parameter</primary>
</indexterm>
</term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
The fillfactor for a table is a percentage between 10 and 100.
100 (complete packing) is the default. When a smaller fillfactor
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
is specified, <command>INSERT</command> operations pack table pages only
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
to the indicated percentage; the remaining space on each page is
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
reserved for updating rows on that page. This gives <command>UPDATE</command>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
a chance to place the updated copy of a row on the same page as the
doc: add section about heap-only tuples (HOT) Reported-by: Jonathan S. Katz Discussion: https://postgr.es/m/c59ffbd5-96ac-a5a5-a401-14f627ca1405@postgresql.org Backpatch-through: 11
2022-08-12 21:05:13 +02:00
original, which is more efficient than placing it on a different
page, and makes <link linkend="storage-hot">heap-only tuple
updates</link> more likely.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
For a table whose entries are never updated, complete packing is the
best choice, but in heavily updated tables smaller fillfactors are
Use "TOAST table" in place of the vague, not-used-elsewhere phrase "supplementary storage table".
2010-05-13 20:54:18 +02:00
appropriate. This parameter cannot be set for TOAST tables.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
</listitem>
Allow reloption names to have qualifiers, initially supporting a TOAST qualifier, and add support for this in pg_dump. This allows TOAST tables to have user-defined fillfactor, and will also enable us to move the autovacuum parameters to reloptions without taking away the possibility of setting values for TOAST tables.
2009-02-02 20:31:40 +01:00
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-toast-tuple-target" xreflabel="toast_tuple_target">
<term><literal>toast_tuple_target</literal> (<type>integer</type>)
<indexterm>
<primary><varname>toast_tuple_target</varname> storage parameter</primary>
</indexterm>
</term>
Parameter toast_tuple_target controls TOAST for new rows Specifies the point at which we try to move long column values into TOAST tables. No effect on existing rows. Discussion: https://postgr.es/m/CANP8+jKsVmw6CX6YP9z7zqkTzcKV1+Uzr3XjKcZW=2Ya00OyQQ@mail.gmail.com Author: Simon Riggs <simon@2ndQudrant.com> Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndQuadrant.com>
2017-11-19 23:50:10 +01:00
<listitem>
<para>
The toast_tuple_target specifies the minimum tuple length required before
doc: Mention that toast_tuple_target affects also column marked as Main. Previously it was documented that toast_tuple_target affected column marked as only External or Extended. But this description is not correct and toast_tuple_target affects also column marked as Main. Back-patch to v11 where toast_tuple_target reloption was introduced. Author: Shinya Okano Reviewed-by: Tatsuhito Kasahara, Fujii Masao Discussion: https://postgr.es/m/93f46e311a67422e89e770d236059817@oss.nttdata.com
2020-10-15 04:04:07 +02:00
we try to compress and/or move long column values into TOAST tables, and
is also the target length we try to reduce the length below once toasting
begins. This affects columns marked as External (for move),
Main (for compression), or Extended (for both) and applies only to new
tuples. There is no effect on existing rows.
Parameter toast_tuple_target controls TOAST for new rows Specifies the point at which we try to move long column values into TOAST tables. No effect on existing rows. Discussion: https://postgr.es/m/CANP8+jKsVmw6CX6YP9z7zqkTzcKV1+Uzr3XjKcZW=2Ya00OyQQ@mail.gmail.com Author: Simon Riggs <simon@2ndQudrant.com> Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndQuadrant.com>
2017-11-19 23:50:10 +01:00
By default this parameter is set to allow at least 4 tuples per block,
doc: Spell checking
2020-07-05 15:37:57 +02:00
which with the default block size will be 2040 bytes. Valid values are
between 128 bytes and the (block size - header), by default 8160 bytes.
Parameter toast_tuple_target controls TOAST for new rows Specifies the point at which we try to move long column values into TOAST tables. No effect on existing rows. Discussion: https://postgr.es/m/CANP8+jKsVmw6CX6YP9z7zqkTzcKV1+Uzr3XjKcZW=2Ya00OyQQ@mail.gmail.com Author: Simon Riggs <simon@2ndQudrant.com> Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndQuadrant.com>
2017-11-19 23:50:10 +01:00
Changing this value may not be useful for very short or very long rows.
Note that the default setting is often close to optimal, and
it is possible that setting this parameter could have negative
effects in some cases.
This parameter cannot be set for TOAST tables.
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-parallel-workers" xreflabel="parallel_workers">
<term><literal>parallel_workers</literal> (<type>integer</type>)
<indexterm>
<primary><varname>parallel_workers</varname> storage parameter</primary>
</indexterm>
</term>
Add a 'parallel_degree' reloption. The code that estimates what parallel degree should be uesd for the scan of a relation is currently rather stupid, so add a parallel_degree reloption that can be used to override the planner's rather limited judgement. Julien Rouhaud, reviewed by David Rowley, James Sewell, Amit Kapila, and me. Some further hacking by me.
2016-04-08 17:14:56 +02:00
<listitem>
<para>
Eliminate "parallel degree" terminology. This terminology provoked widespread complaints. So, instead, rename the GUC max_parallel_degree to max_parallel_workers_per_gather (leaving room for a possible future GUC max_parallel_workers that acts as a system-wide limit), and rename the parallel_degree reloption to parallel_workers. Rename structure members to match. These changes create a dump/restore hazard for users of PostgreSQL 9.6beta1 who have set the reloption (or applied the GUC using ALTER USER or ALTER DATABASE).
2016-06-09 15:08:27 +02:00
This sets the number of workers that should be used to assist a parallel
scan of this table. If not set, the system will determine a value based
on the relation size. The actual number of workers chosen by the planner
Support parallel btree index builds. To make this work, tuplesort.c and logtape.c must also support parallelism, so this patch adds that infrastructure and then applies it to the particular case of parallel btree index builds. Testing to date shows that this can often be 2-3x faster than a serial index build. The model for deciding how many workers to use is fairly primitive at present, but it's better than not having the feature. We can refine it as we get more experience. Peter Geoghegan with some help from Rushabh Lathia. While Heikki Linnakangas is not an author of this patch, he wrote other patches without which this feature would not have been possible, and therefore the release notes should possibly credit him as an author of this feature. Reviewed by Claudio Freire, Heikki Linnakangas, Thomas Munro, Tels, Amit Kapila, me. Discussion: http://postgr.es/m/CAM3SWZQKM=Pzc=CAHzRixKjp2eO5Q0Jg1SoFQqeXFQ647JiwqQ@mail.gmail.com Discussion: http://postgr.es/m/CAH2-Wz=AxWqDoVvGU7dq856S4r6sJAj6DBn7VMtigkB33N5eyg@mail.gmail.com
2018-02-02 19:25:55 +01:00
or by utility statements that use parallel scans may be less, for example
due to the setting of <xref linkend="guc-max-worker-processes"/>.
Add a 'parallel_degree' reloption. The code that estimates what parallel degree should be uesd for the scan of a relation is currently rather stupid, so add a parallel_degree reloption that can be used to override the planner's rather limited judgement. Julien Rouhaud, reviewed by David Rowley, James Sewell, Amit Kapila, and me. Some further hacking by me.
2016-04-08 17:14:56 +02:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-enabled" xreflabel="autovacuum_enabled">
<term><literal>autovacuum_enabled</literal>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</type>)
<indexterm>
<primary><varname>autovacuum_enabled</varname> storage parameter</primary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Enables or disables the autovacuum daemon for a particular table.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If true, the autovacuum daemon will perform automatic <command>VACUUM</command>
and/or <command>ANALYZE</command> operations on this table following the rules
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
discussed in <xref linkend="autovacuum"/>.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
If false, this table will not be autovacuumed, except to prevent
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
transaction ID wraparound. See <xref linkend="vacuum-for-wraparound"/> for
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
more about wraparound prevention.
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Note that the autovacuum daemon does not run at all (except to prevent
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
transaction ID wraparound) if the <xref linkend="guc-autovacuum"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter is false; setting individual tables' storage parameters does
not override that. Therefore there is seldom much point in explicitly
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
setting this storage parameter to <literal>true</literal>, only
to <literal>false</literal>.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-vacuum-index-cleanup" xreflabel="vacuum_index_cleanup">
Support disabling index bypassing by VACUUM. Generalize the INDEX_CLEANUP VACUUM parameter (and the corresponding reloption): make it into a ternary style boolean parameter. It now exposes a third option, "auto". The "auto" option (which is now the default) enables the "bypass index vacuuming" optimization added by commit 1e55e7d1. "VACUUM (INDEX_CLEANUP TRUE)" is redefined to once again make VACUUM simply do any required index vacuuming, regardless of how few dead tuples are encountered during the first scan of the target heap relation (unless there are exactly zero). This gives users a way of opting out of the "bypass index vacuuming" optimization, if for whatever reason that proves necessary. It is also expected to be used by PostgreSQL developers as a testing option from time to time. "VACUUM (INDEX_CLEANUP FALSE)" does the same thing as it always has: it forcibly disables both index vacuuming and index cleanup. It's not expected to be used much in PostgreSQL 14. The failsafe mechanism added by commit 1e55e7d1 addresses the same problem in a simpler way. INDEX_CLEANUP can now be thought of as a testing and compatibility option. Author: Peter Geoghegan <pg@bowt.ie> Reviewed-By: Masahiko Sawada <sawada.mshk@gmail.com> Reviewed-By: Justin Pryzby <pryzby@telsasoft.com> Discussion: https://postgr.es/m/CAH2-WznrBoCST4_Gxh_G9hA8NzGUbeBGnOUC8FcXcrhqsv6OHQ@mail.gmail.com
2021-06-19 05:04:07 +02:00
<term><literal>vacuum_index_cleanup</literal>, <literal>toast.vacuum_index_cleanup</literal> (<type>enum</type>)
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<indexterm>
<primary><varname>vacuum_index_cleanup</varname> storage parameter</primary>
</indexterm>
</term>
Allow VACUUM to be run with index cleanup disabled. This commit adds a new reloption, vacuum_index_cleanup, which controls whether index cleanup is performed for a particular relation by default. It also adds a new option to the VACUUM command, INDEX_CLEANUP, which can be used to override the reloption. If neither the reloption nor the VACUUM option is used, the default is true, as before. Masahiko Sawada, reviewed and tested by Nathan Bossart, Alvaro Herrera, Kyotaro Horiguchi, Darafei Praliaskouski, and me. The wording of the documentation is mostly due to me. Discussion: http://postgr.es/m/CAD21AoAt5R3DNUZSjOoXDUY=naYPUOuffVsRzuTYMz29yLzQCA@mail.gmail.com
2019-04-04 20:58:53 +02:00
<listitem>
<para>
Support disabling index bypassing by VACUUM. Generalize the INDEX_CLEANUP VACUUM parameter (and the corresponding reloption): make it into a ternary style boolean parameter. It now exposes a third option, "auto". The "auto" option (which is now the default) enables the "bypass index vacuuming" optimization added by commit 1e55e7d1. "VACUUM (INDEX_CLEANUP TRUE)" is redefined to once again make VACUUM simply do any required index vacuuming, regardless of how few dead tuples are encountered during the first scan of the target heap relation (unless there are exactly zero). This gives users a way of opting out of the "bypass index vacuuming" optimization, if for whatever reason that proves necessary. It is also expected to be used by PostgreSQL developers as a testing option from time to time. "VACUUM (INDEX_CLEANUP FALSE)" does the same thing as it always has: it forcibly disables both index vacuuming and index cleanup. It's not expected to be used much in PostgreSQL 14. The failsafe mechanism added by commit 1e55e7d1 addresses the same problem in a simpler way. INDEX_CLEANUP can now be thought of as a testing and compatibility option. Author: Peter Geoghegan <pg@bowt.ie> Reviewed-By: Masahiko Sawada <sawada.mshk@gmail.com> Reviewed-By: Justin Pryzby <pryzby@telsasoft.com> Discussion: https://postgr.es/m/CAH2-WznrBoCST4_Gxh_G9hA8NzGUbeBGnOUC8FcXcrhqsv6OHQ@mail.gmail.com
2021-06-19 05:04:07 +02:00
Forces or disables index cleanup when <command>VACUUM</command>
is run on this table. The default value is
<literal>AUTO</literal>. With <literal>OFF</literal>, index
cleanup is disabled, with <literal>ON</literal> it is enabled,
and with <literal>AUTO</literal> a decision is made dynamically,
each time <command>VACUUM</command> runs. The dynamic behavior
allows <command>VACUUM</command> to avoid needlessly scanning
indexes to remove very few dead tuples. Forcibly disabling all
index cleanup can speed up <command>VACUUM</command> very
significantly, but may also lead to severely bloated indexes if
table modifications are frequent. The
<literal>INDEX_CLEANUP</literal> parameter of <link
linkend="sql-vacuum"><command>VACUUM</command></link>, if
specified, overrides the value of this option.
Allow VACUUM to be run with index cleanup disabled. This commit adds a new reloption, vacuum_index_cleanup, which controls whether index cleanup is performed for a particular relation by default. It also adds a new option to the VACUUM command, INDEX_CLEANUP, which can be used to override the reloption. If neither the reloption nor the VACUUM option is used, the default is true, as before. Masahiko Sawada, reviewed and tested by Nathan Bossart, Alvaro Herrera, Kyotaro Horiguchi, Darafei Praliaskouski, and me. The wording of the documentation is mostly due to me. Discussion: http://postgr.es/m/CAD21AoAt5R3DNUZSjOoXDUY=naYPUOuffVsRzuTYMz29yLzQCA@mail.gmail.com
2019-04-04 20:58:53 +02:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-vacuum-truncate" xreflabel="vacuum_truncate">
<term><literal>vacuum_truncate</literal>, <literal>toast.vacuum_truncate</literal> (<type>boolean</type>)
<indexterm>
<primary><varname>vacuum_truncate</varname> storage parameter</primary>
</indexterm>
</term>
Add vacuum_truncate reloption. vacuum_truncate controls whether vacuum tries to truncate off any empty pages at the end of the table. Previously vacuum always tried to do the truncation. However, the truncation could cause some problems; for example, ACCESS EXCLUSIVE lock needs to be taken on the table during the truncation and can cause the query cancellation on the standby even if hot_standby_feedback is true. Setting this reloption to false can be helpful to avoid such problems. Author: Tsunakawa Takayuki Reviewed-By: Julien Rouhaud, Masahiko Sawada, Michael Paquier, Kirk Jamison and Fujii Masao Discussion: https://postgr.es/m/CAHGQGwE5UqFqSq1=kV3QtTUtXphTdyHA-8rAj4A=Y+e4kyp3BQ@mail.gmail.com
2019-04-08 09:43:57 +02:00
<listitem>
<para>
Enables or disables vacuum to try to truncate off any empty pages
at the end of this table. The default value is <literal>true</literal>.
If <literal>true</literal>, <command>VACUUM</command> and
autovacuum do the truncation and the disk space for
the truncated pages is returned to the operating system.
Note that the truncation requires <literal>ACCESS EXCLUSIVE</literal>
Add TRUNCATE parameter to VACUUM. This commit adds new parameter to VACUUM command, TRUNCATE, which specifies that VACUUM should attempt to truncate off any empty pages at the end of the table and allow the disk space for the truncated pages to be returned to the operating system. This parameter, if specified, overrides the vacuum_truncate reloption. If neither the reloption nor the VACUUM option is used, the default is true, as before. Author: Fujii Masao Reviewed-by: Julien Rouhaud, Masahiko Sawada Discussion: https://postgr.es/m/CAD21AoD+qtrSDL=GSma4Wd3kLYLeRC0hPna-YAdkDeV4z156vg@mail.gmail.com
2019-05-07 19:10:33 +02:00
lock on the table. The <literal>TRUNCATE</literal> parameter
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
of <link linkend="sql-vacuum"><command>VACUUM</command></link>, if specified, overrides the value
Add TRUNCATE parameter to VACUUM. This commit adds new parameter to VACUUM command, TRUNCATE, which specifies that VACUUM should attempt to truncate off any empty pages at the end of the table and allow the disk space for the truncated pages to be returned to the operating system. This parameter, if specified, overrides the vacuum_truncate reloption. If neither the reloption nor the VACUUM option is used, the default is true, as before. Author: Fujii Masao Reviewed-by: Julien Rouhaud, Masahiko Sawada Discussion: https://postgr.es/m/CAD21AoD+qtrSDL=GSma4Wd3kLYLeRC0hPna-YAdkDeV4z156vg@mail.gmail.com
2019-05-07 19:10:33 +02:00
of this option.
Add vacuum_truncate reloption. vacuum_truncate controls whether vacuum tries to truncate off any empty pages at the end of the table. Previously vacuum always tried to do the truncation. However, the truncation could cause some problems; for example, ACCESS EXCLUSIVE lock needs to be taken on the table during the truncation and can cause the query cancellation on the standby even if hot_standby_feedback is true. Setting this reloption to false can be helpful to avoid such problems. Author: Tsunakawa Takayuki Reviewed-By: Julien Rouhaud, Masahiko Sawada, Michael Paquier, Kirk Jamison and Fujii Masao Discussion: https://postgr.es/m/CAHGQGwE5UqFqSq1=kV3QtTUtXphTdyHA-8rAj4A=Y+e4kyp3BQ@mail.gmail.com
2019-04-08 09:43:57 +02:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold">
<term><literal>autovacuum_vacuum_threshold</literal>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_vacuum_threshold</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-vacuum-threshold"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Fix typos and grammar in documentation and code comments Comment fixes are applied on HEAD, and documentation improvements are applied on back-branches where needed. Author: Justin Pryzby Discussion: https://postgr.es/m/20210408164008.GJ6592@telsasoft.com Backpatch-through: 9.6
2021-04-09 06:53:07 +02:00
<varlistentry id="reloption-autovacuum-vacuum-scale-factor" xreflabel="autovacuum_vacuum_scale_factor">
Doc: Fix type of some storage parameters in CREATE TABLE page autovacuum_vacuum_scale_factor and autovacuum_analyze_scale_factor have been documented as "float4", but "floating type" is used in this case for GUCs and relation options in the documentation. Author: Atsushi Torikoshi Discussion: https://postgr.es/m/CACZ0uYFf_p9BpbjLccx3CA=eM1Hk2Te=ULY4iptGLUhL-JxCPA@mail.gmail.com Backpatch-through: 9.5
2020-03-23 05:38:03 +01:00
<term><literal>autovacuum_vacuum_scale_factor</literal>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>floating point</type>)
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<indexterm>
<primary><varname>autovacuum_vacuum_scale_factor</varname> </primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-vacuum-scale-factor"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Trigger autovacuum based on number of INSERTs Traditionally autovacuum has only ever invoked a worker based on the estimated number of dead tuples in a table and for anti-wraparound purposes. For the latter, with certain classes of tables such as insert-only tables, anti-wraparound vacuums could be the first vacuum that the table ever receives. This could often lead to autovacuum workers being busy for extended periods of time due to having to potentially freeze every page in the table. This could be particularly bad for very large tables. New clusters, or recently pg_restored clusters could suffer even more as many large tables may have the same relfrozenxid, which could result in large numbers of tables requiring an anti-wraparound vacuum all at once. Here we aim to reduce the work required by anti-wraparound and aggressive vacuums in general, by triggering autovacuum when the table has received enough INSERTs. This is controlled by adding two new GUCs and reloptions; autovacuum_vacuum_insert_threshold and autovacuum_vacuum_insert_scale_factor. These work exactly the same as the existing scale factor and threshold controls, only base themselves off the number of inserts since the last vacuum, rather than the number of dead tuples. New controls were added rather than reusing the existing controls, to allow these new vacuums to be tuned independently and perhaps even completely disabled altogether, which can be done by setting autovacuum_vacuum_insert_threshold to -1. We make no attempt to skip index cleanup operations on these vacuums as they may trigger for an insert-mostly table which continually doesn't have enough dead tuples to trigger an autovacuum for the purpose of removing those dead tuples. If we were to skip cleaning the indexes in this case, then it is possible for the index(es) to become bloated over time. There are additional benefits to triggering autovacuums based on inserts, as tables which never contain enough dead tuples to trigger an autovacuum are now more likely to receive a vacuum, which can mark more of the table as "allvisible" and encourage the query planner to make use of Index Only Scans. Currently, we still obey vacuum_freeze_min_age when triggering these new autovacuums based on INSERTs. For large insert-only tables, it may be beneficial to lower the table's autovacuum_freeze_min_age so that tuples are eligible to be frozen sooner. Here we've opted not to zero that for these types of vacuums, since the table may just be insert-mostly and we may otherwise freeze tuples that are still destined to be updated or removed in the near future. There was some debate to what exactly the new scale factor and threshold should default to. For now, these are set to 0.2 and 1000, respectively. There may be some motivation to adjust these before the release. Author: Laurenz Albe, Darafei Praliaskouski Reviewed-by: Alvaro Herrera, Masahiko Sawada, Chris Travers, Andres Freund, Justin Pryzby Discussion: https://postgr.es/m/CAC8Q8t%2Bj36G_bLF%3D%2B0iMo6jGNWnLnWb1tujXuJr-%2Bx8ZCCTqoQ%40mail.gmail.com
2020-03-28 07:20:12 +01:00
<varlistentry id="reloption-autovacuum-vacuum-insert-threshold" xreflabel="autovacuum_vacuum_insert_threshold">
<term><literal>autovacuum_vacuum_insert_threshold</literal>, <literal>toast.autovacuum_vacuum_insert_threshold</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_vacuum_insert_threshold</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
<listitem>
<para>
Per-table value for <xref linkend="guc-autovacuum-vacuum-insert-threshold"/>
parameter. The special value of -1 may be used to disable insert vacuums on the table.
</para>
</listitem>
</varlistentry>
<varlistentry id="reloption-autovacuum-vacuum-insert-scale-factor" xreflabel="autovacuum_vacuum_insert_scale_factor">
doc: Change reloption data type spelling for consistency Use "floating point" rather than "float4", like everywhere else in this context. Author: Shinya11.Kato@nttdata.com Discussion: https://www.postgresql.org/message-id/flat/TYAPR01MB28965989AF84B57FC351B97BC40F9@TYAPR01MB2896.jpnprd01.prod.outlook.com
2021-06-25 08:11:10 +02:00
<term><literal>autovacuum_vacuum_insert_scale_factor</literal>, <literal>toast.autovacuum_vacuum_insert_scale_factor</literal> (<type>floating point</type>)
Trigger autovacuum based on number of INSERTs Traditionally autovacuum has only ever invoked a worker based on the estimated number of dead tuples in a table and for anti-wraparound purposes. For the latter, with certain classes of tables such as insert-only tables, anti-wraparound vacuums could be the first vacuum that the table ever receives. This could often lead to autovacuum workers being busy for extended periods of time due to having to potentially freeze every page in the table. This could be particularly bad for very large tables. New clusters, or recently pg_restored clusters could suffer even more as many large tables may have the same relfrozenxid, which could result in large numbers of tables requiring an anti-wraparound vacuum all at once. Here we aim to reduce the work required by anti-wraparound and aggressive vacuums in general, by triggering autovacuum when the table has received enough INSERTs. This is controlled by adding two new GUCs and reloptions; autovacuum_vacuum_insert_threshold and autovacuum_vacuum_insert_scale_factor. These work exactly the same as the existing scale factor and threshold controls, only base themselves off the number of inserts since the last vacuum, rather than the number of dead tuples. New controls were added rather than reusing the existing controls, to allow these new vacuums to be tuned independently and perhaps even completely disabled altogether, which can be done by setting autovacuum_vacuum_insert_threshold to -1. We make no attempt to skip index cleanup operations on these vacuums as they may trigger for an insert-mostly table which continually doesn't have enough dead tuples to trigger an autovacuum for the purpose of removing those dead tuples. If we were to skip cleaning the indexes in this case, then it is possible for the index(es) to become bloated over time. There are additional benefits to triggering autovacuums based on inserts, as tables which never contain enough dead tuples to trigger an autovacuum are now more likely to receive a vacuum, which can mark more of the table as "allvisible" and encourage the query planner to make use of Index Only Scans. Currently, we still obey vacuum_freeze_min_age when triggering these new autovacuums based on INSERTs. For large insert-only tables, it may be beneficial to lower the table's autovacuum_freeze_min_age so that tuples are eligible to be frozen sooner. Here we've opted not to zero that for these types of vacuums, since the table may just be insert-mostly and we may otherwise freeze tuples that are still destined to be updated or removed in the near future. There was some debate to what exactly the new scale factor and threshold should default to. For now, these are set to 0.2 and 1000, respectively. There may be some motivation to adjust these before the release. Author: Laurenz Albe, Darafei Praliaskouski Reviewed-by: Alvaro Herrera, Masahiko Sawada, Chris Travers, Andres Freund, Justin Pryzby Discussion: https://postgr.es/m/CAC8Q8t%2Bj36G_bLF%3D%2B0iMo6jGNWnLnWb1tujXuJr-%2Bx8ZCCTqoQ%40mail.gmail.com
2020-03-28 07:20:12 +01:00
<indexterm>
<primary><varname>autovacuum_vacuum_insert_scale_factor</varname> </primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
<listitem>
<para>
Per-table value for <xref linkend="guc-autovacuum-vacuum-insert-scale-factor"/>
parameter.
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold">
<term><literal>autovacuum_analyze_threshold</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_analyze_threshold</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-analyze-threshold"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-analyze-scale-factor" xreflabel="autovacuum_analyze_scale_factor">
Doc: Fix type of some storage parameters in CREATE TABLE page autovacuum_vacuum_scale_factor and autovacuum_analyze_scale_factor have been documented as "float4", but "floating type" is used in this case for GUCs and relation options in the documentation. Author: Atsushi Torikoshi Discussion: https://postgr.es/m/CACZ0uYFf_p9BpbjLccx3CA=eM1Hk2Te=ULY4iptGLUhL-JxCPA@mail.gmail.com Backpatch-through: 9.5
2020-03-23 05:38:03 +01:00
<term><literal>autovacuum_analyze_scale_factor</literal> (<type>floating point</type>)
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<indexterm>
<primary><varname>autovacuum_analyze_scale_factor</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-analyze-scale-factor"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay">
<term><literal>autovacuum_vacuum_cost_delay</literal>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>floating point</type>)
<indexterm>
<primary><varname>autovacuum_vacuum_cost_delay</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-delay"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Fix typos and grammar in documentation and code comments Comment fixes are applied on HEAD, and documentation improvements are applied on back-branches where needed. Author: Justin Pryzby Discussion: https://postgr.es/m/20210408164008.GJ6592@telsasoft.com Backpatch-through: 9.6
2021-04-09 06:53:07 +02:00
<varlistentry id="reloption-autovacuum-vacuum-cost-limit" xreflabel="autovacuum_vacuum_cost_limit">
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<term><literal>autovacuum_vacuum_cost_limit</literal>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_vacuum_cost_limit</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-limit"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-freeze-min-age" xreflabel="autovacuum_freeze_min_age">
<term><literal>autovacuum_freeze_min_age</literal>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_freeze_min_age</varname> storage parameter</primary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-vacuum-freeze-min-age"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter. Note that autovacuum will ignore
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
per-table <literal>autovacuum_freeze_min_age</literal> parameters that are
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
larger than half the
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
system-wide <xref linkend="guc-autovacuum-freeze-max-age"/> setting.
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-freeze-max-age" xreflabel="autovacuum_freeze_max_age">
<term><literal>autovacuum_freeze_max_age</literal>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_freeze_max_age</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-autovacuum-freeze-max-age"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter. Note that autovacuum will ignore
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
per-table <literal>autovacuum_freeze_max_age</literal> parameters that are
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
larger than the system-wide setting (it can only be set smaller).
Update autovacuum to use reloptions instead of a system catalog, for per-table overrides of parameters. This removes a whole class of problems related to misusing the catalog, and perhaps more importantly, gives us pg_dump support for the parameters. Based on a patch by Euler Taveira de Oliveira, heavily reworked by me.
2009-02-09 21:57:59 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-freeze-table-age" xreflabel="autovacuum_freeze_table_age">
<term><literal>autovacuum_freeze_table_age</literal>, <literal>toast.autovacuum_freeze_table_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_freeze_table_age</varname> storage parameter</primary>
</indexterm>
</term>
Allow reloption names to have qualifiers, initially supporting a TOAST qualifier, and add support for this in pg_dump. This allows TOAST tables to have user-defined fillfactor, and will also enable us to move the autovacuum parameters to reloptions without taking away the possibility of setting values for TOAST tables.
2009-02-02 20:31:40 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-vacuum-freeze-table-age"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Allow reloption names to have qualifiers, initially supporting a TOAST qualifier, and add support for this in pg_dump. This allows TOAST tables to have user-defined fillfactor, and will also enable us to move the autovacuum parameters to reloptions without taking away the possibility of setting values for TOAST tables.
2009-02-02 20:31:40 +01:00
</para>
</listitem>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-multixact-freeze-min-age" xreflabel="autovacuum_multixact_freeze_min_age">
<term><literal>autovacuum_multixact_freeze_min_age</literal>, <literal>toast.autovacuum_multixact_freeze_min_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_multixact_freeze_min_age</varname> storage parameter</primary>
</indexterm>
</term>
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-vacuum-multixact-freeze-min-age"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter. Note that autovacuum will ignore
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
per-table <literal>autovacuum_multixact_freeze_min_age</literal> parameters
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
that are larger than half the
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
setting.
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-multixact-freeze-max-age" xreflabel="autovacuum_multixact_freeze_max_age">
<term><literal>autovacuum_multixact_freeze_max_age</literal>, <literal>toast.autovacuum_multixact_freeze_max_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_multixact_freeze_max_age</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
<listitem>
<para>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Per-table value
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
for <xref linkend="guc-autovacuum-multixact-freeze-max-age"/> parameter.
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Note that autovacuum will ignore
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
per-table <literal>autovacuum_multixact_freeze_max_age</literal> parameters
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
that are larger than the system-wide setting (it can only be set
smaller).
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-autovacuum-multixact-freeze-table-age" xreflabel="autovacuum_multixact_freeze_table_age">
<term><literal>autovacuum_multixact_freeze_table_age</literal>, <literal>toast.autovacuum_multixact_freeze_table_age</literal> (<type>integer</type>)
<indexterm>
<primary><varname>autovacuum_multixact_freeze_table_age</varname> storage parameter</primary>
</indexterm>
</term>
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
<listitem>
<para>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Per-table value
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
for <xref linkend="guc-vacuum-multixact-freeze-table-age"/> parameter.
Separate multixact freezing parameters from xid's Previously we were piggybacking on transaction ID parameters to freeze multixacts; but since there isn't necessarily any relationship between rates of Xid and multixact consumption, this turns out not to be a good idea. Therefore, we now have multixact-specific freezing parameters: vacuum_multixact_freeze_min_age: when to remove multis as we come across them in vacuum (default to 5 million, i.e. early in comparison to Xid's default of 50 million) vacuum_multixact_freeze_table_age: when to force whole-table scans instead of scanning only the pages marked as not all visible in visibility map (default to 150 million, same as for Xids). Whichever of both which reaches the 150 million mark earlier will cause a whole-table scan. autovacuum_multixact_freeze_max_age: when for cause emergency, uninterruptible whole-table scans (default to 400 million, double as that for Xids). This means there shouldn't be more frequent emergency vacuuming than previously, unless multixacts are being used very rapidly. Backpatch to 9.3 where multixacts were made to persist enough to require freezing. To avoid an ABI break in 9.3, VacuumStmt has a couple of fields in an unnatural place, and StdRdOptions is split in two so that the newly added fields can go at the end. Patch by me, reviewed by Robert Haas, with additional input from Andres Freund and Tom Lane.
2014-02-13 23:30:30 +01:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-log-autovacuum-min-duration" xreflabel="log_autovacuum_min_duration">
<term><literal>log_autovacuum_min_duration</literal>, <literal>toast.log_autovacuum_min_duration</literal> (<type>integer</type>)
<indexterm>
<primary><varname>log_autovacuum_min_duration</varname></primary>
<secondary>storage parameter</secondary>
</indexterm>
</term>
Add log_min_autovacuum_duration per-table option This is useful to control autovacuum log volume, for situations where monitoring only a set of tables is necessary. Author: Michael Paquier Reviewed by: A team led by Naoya Anzai (also including Akira Kurosawa, Taiki Kondo, Huong Dangminh), Fujii Masao.
2015-04-03 16:55:50 +02:00
<listitem>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Per-table value for <xref linkend="guc-log-autovacuum-min-duration"/>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
parameter.
Add log_min_autovacuum_duration per-table option This is useful to control autovacuum log volume, for situations where monitoring only a set of tables is necessary. Author: Michael Paquier Reviewed by: A team led by Naoya Anzai (also including Akira Kurosawa, Taiki Kondo, Huong Dangminh), Fujii Masao.
2015-04-03 16:55:50 +02:00
</para>
</listitem>
</varlistentry>
Add index terms for reloptions in documentation. Author: Fujii Masao Reviewed-By: Alvaro Herrera, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHyKt9-xkibVguPzYqKgb_2tdw14Ub1XDTu08kyHMiTQA@mail.gmail.com
2019-04-16 16:16:20 +02:00
<varlistentry id="reloption-user-catalog-table" xreflabel="user_catalog_table">
<term><literal>user_catalog_table</literal> (<type>boolean</type>)
<indexterm>
<primary><varname>user_catalog_table</varname> storage parameter</primary>
</indexterm>
</term>
Documentation for logical decoding. Craig Ringer, Andres Freund, Christian Kruse, with edits by me.
2014-03-18 18:20:01 +01:00
<listitem>
<para>
Improve documentation around autovacuum-related storage parameters. These were discussed in three different sections of the manual, which unsurprisingly had diverged over time; and the descriptions of individual variables lacked stylistic consistency even within each section (and frequently weren't in very good English anyway). Clean up the mess, and remove some of the redundant information in hopes that future additions will be less likely to re-introduce inconsistency. For instance I see no need for maintenance.sgml to include its very own list of all the autovacuum storage parameters, especially since that list was already incomplete.
2015-11-11 23:13:38 +01:00
Declare the table as an additional catalog table for purposes of
Documentation for logical decoding. Craig Ringer, Andres Freund, Christian Kruse, with edits by me.
2014-03-18 18:20:01 +01:00
logical replication. See
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="logicaldecoding-capabilities"/> for details.
Add log_min_autovacuum_duration per-table option This is useful to control autovacuum log volume, for situations where monitoring only a set of tables is necessary. Author: Michael Paquier Reviewed by: A team led by Naoya Anzai (also including Akira Kurosawa, Taiki Kondo, Huong Dangminh), Fujii Masao.
2015-04-03 16:55:50 +02:00
This parameter cannot be set for TOAST tables.
Documentation for logical decoding. Craig Ringer, Andres Freund, Christian Kruse, with edits by me.
2014-03-18 18:20:01 +01:00
</para>
</listitem>
</varlistentry>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</variablelist>
</refsect2>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
</refsect1>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refsect1 id="sql-createtable-notes">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<title>Notes</title>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<productname>PostgreSQL</productname> automatically creates an
index for each unique constraint and primary key constraint to
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
enforce uniqueness. Thus, it is not necessary to create an
index explicitly for primary key columns. (See <xref
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
linkend="sql-createindex"/> for more information.)
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Unique constraints and primary keys are not inherited in the
current implementation. This makes the combination of
Spell-check and markup police
2002-01-20 23:19:57 +01:00
inheritance and unique constraints rather dysfunctional.
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
</para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<para>
A table cannot have more than 1600 columns. (In practice, the
effective limit is usually lower because of tuple-length constraints.)
</para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</refsect1>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refsect1 id="sql-createtable-examples">
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<title>Examples</title>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Create table <structname>films</structname> and table
<structname>distributors</structname>:
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE films (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
code char(5) CONSTRAINT firstkey PRIMARY KEY,
title varchar(40) NOT NULL,
did integer NOT NULL,
date_prod date,
kind varchar(10),
len interval hour to minute
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
);
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE distributors (
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
did integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
More editing of reference pages.
2003-04-22 12:08:08 +02:00
name varchar(40) NOT NULL CHECK (name &lt;&gt; '')
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Create a table with a 2-dimensional array:
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix example, change table name from 'array' to 'array_int'.
2005-01-05 19:03:19 +01:00
CREATE TABLE array_int (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
vector int[][]
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
);
</programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
Define a unique table constraint for the table
<literal>films</literal>. Unique table constraints can be defined
Consistenly use colons before '<programlisting>' blocks, where appropriate.
2007-02-01 01:28:19 +01:00
on one or more columns of the table:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE films (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
code char(5),
title varchar(40),
did integer,
date_prod date,
kind varchar(10),
len interval hour to minute,
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CONSTRAINT production UNIQUE(date_prod)
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Define a check column constraint:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE distributors (
More < and > changes to ampersands. 8.0.X and HEAD.
2005-01-23 00:22:19 +01:00
did integer CHECK (did &gt; 100),
More editing of reference pages.
2003-04-22 12:08:08 +02:00
name varchar(40)
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Define a check table constraint:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer,
Doc: fix minor bug in CREATE TABLE example. One example in create_table.sgml claimed to be showing table constraint syntax, but it was really column constraint syntax due to the omission of a comma. This is both wrong and confusing, so fix it in all supported branches. Per report from neil@postgrescompare.com. Discussion: https://postgr.es/m/151871659877.1393.2431103178451978795@wrigleys.postgresql.org
2018-02-15 19:56:38 +01:00
name varchar(40),
More < and > changes to ampersands. 8.0.X and HEAD.
2005-01-23 00:22:19 +01:00
CONSTRAINT con1 CHECK (did &gt; 100 AND name &lt;&gt; '')
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Define a primary key table constraint for the table
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<structname>films</structname>:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE films (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
code char(5),
title varchar(40),
did integer,
date_prod date,
kind varchar(10),
len interval hour to minute,
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CONSTRAINT code_title PRIMARY KEY(code,title)
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Define a primary key constraint for table
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<structname>distributors</structname>. The following two examples are
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
equivalent, the first using the table constraint syntax, the second
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
the column constraint syntax:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer,
name varchar(40),
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
PRIMARY KEY(did)
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
);
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer PRIMARY KEY,
name varchar(40)
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
);
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Assign a literal constant default value for the column
<literal>name</literal>, arrange for the default value of column
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<literal>did</literal> to be generated by selecting the next value
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
of a sequence object, and make the default value of
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<literal>modtime</literal> be the time at which the row is
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
inserted:
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
name varchar(40) DEFAULT 'Luso Films',
did integer DEFAULT nextval('distributors_serial'),
modtime timestamp DEFAULT current_timestamp
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
);
</programlisting>
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Define two <literal>NOT NULL</literal> column constraints on the table
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<classname>distributors</classname>, one of which is explicitly
given a name:
<programlisting>
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer CONSTRAINT no_null NOT NULL,
name varchar(40) NOT NULL
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
);
</programlisting>
</para>
<para>
Define a unique constraint for the <literal>name</literal> column:
<programlisting>
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer,
name varchar(40) UNIQUE
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
);
</programlisting>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
The same, specified as a table constraint:
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<programlisting>
CREATE TABLE distributors (
More editing of reference pages.
2003-04-22 12:08:08 +02:00
did integer,
name varchar(40),
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
UNIQUE(name)
);
Tablespace examples for CREATE TABLE/INDEX/SCHEMA/DATABASE as well as some other examples for CREATE DATABASE. Gavin Sherry
2004-07-12 03:22:53 +02:00
</programlisting>
</para>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<para>
Create the same table, specifying 70% fill factor for both the table
and its unique index:
<programlisting>
CREATE TABLE distributors (
did integer,
name varchar(40),
UNIQUE(name) WITH (fillfactor=70)
)
WITH (fillfactor=70);
</programlisting>
</para>
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Create table <structname>circles</structname> with an exclusion
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
constraint that prevents any two circles from overlapping:
<programlisting>
CREATE TABLE circles (
c circle,
Entity-ify a few new uses of literal <, >, and &.
2010-02-27 05:29:44 +01:00
EXCLUDE USING gist (c WITH &amp;&amp;)
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
);
</programlisting>
</para>
Tablespace examples for CREATE TABLE/INDEX/SCHEMA/DATABASE as well as some other examples for CREATE DATABASE. Gavin Sherry
2004-07-12 03:22:53 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Create table <structname>cinemas</structname> in tablespace <structname>diskvol1</structname>:
Tablespace examples for CREATE TABLE/INDEX/SCHEMA/DATABASE as well as some other examples for CREATE DATABASE. Gavin Sherry
2004-07-12 03:22:53 +02:00
<programlisting>
CREATE TABLE cinemas (
Disallow referential integrity actions from being deferred; only the NO ACTION check is deferrable. This seems to be a closer approximation to what the SQL spec says than what we were doing before, and it prevents some anomalous behaviors that are possible now that triggers can fire during the execution of PL functions. Stephan Szabo.
2004-10-21 23:33:59 +02:00
id serial,
name text,
location text
Tablespace examples for CREATE TABLE/INDEX/SCHEMA/DATABASE as well as some other examples for CREATE DATABASE. Gavin Sherry
2004-07-12 03:22:53 +02:00
) TABLESPACE diskvol1;
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</programlisting>
</para>
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
<para>
Create a composite type and a typed table:
<programlisting>
CREATE TYPE employee_type AS (name text, salary numeric);
CREATE TABLE employees OF employee_type (
PRIMARY KEY (name),
salary WITH OPTIONS DEFAULT 1000
);
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</programlisting></para>
<para>
Create a range partitioned table:
<programlisting>
CREATE TABLE measurement (
logdate date not null,
peaktemp int,
unitsales int
) PARTITION BY RANGE (logdate);
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
</programlisting></para>
<para>
Create a range partitioned table with multiple columns in the partition key:
<programlisting>
CREATE TABLE measurement_year_month (
logdate date not null,
peaktemp int,
unitsales int
) PARTITION BY RANGE (EXTRACT(YEAR FROM logdate), EXTRACT(MONTH FROM logdate));
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</programlisting></para>
<para>
Create a list partitioned table:
<programlisting>
CREATE TABLE cities (
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
city_id bigserial not null,
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
name text not null,
doc: Fix typos From: Thom Brown <thom@linux.com>
2017-02-18 00:59:29 +01:00
population bigint
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
) PARTITION BY LIST (left(lower(name), 1));
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
</programlisting></para>
<para>
Create a hash partitioned table:
<programlisting>
CREATE TABLE orders (
order_id bigint not null,
cust_id bigint not null,
status text
) PARTITION BY HASH (order_id);
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</programlisting></para>
<para>
Create partition of a range partitioned table:
<programlisting>
CREATE TABLE measurement_y2016m07
PARTITION OF measurement (
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
unitsales DEFAULT 0
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
) FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
</programlisting></para>
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<para>
Create a few partitions of a range partitioned table with multiple
columns in the partition key:
<programlisting>
CREATE TABLE measurement_ym_older
PARTITION OF measurement_year_month
After a MINVALUE/MAXVALUE bound, allow only more of the same. In the old syntax, which used UNBOUNDED, we had a similar restriction, but commit d363d42bb9a4399a0207bd3b371c966e22e06bd3, which changed the syntax, eliminated it. Put it back. Patch by me, reviewed by Dean Rasheed. Discussion: http://postgr.es/m/CA+Tgmobs+pLPC27tS3gOpEAxAffHrq5w509cvkwTf9pF6cWYbg@mail.gmail.com
2017-09-16 03:15:55 +02:00
FOR VALUES FROM (MINVALUE, MINVALUE) TO (2016, 11);
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
CREATE TABLE measurement_ym_y2016m11
PARTITION OF measurement_year_month
FOR VALUES FROM (2016, 11) TO (2016, 12);
CREATE TABLE measurement_ym_y2016m12
PARTITION OF measurement_year_month
FOR VALUES FROM (2016, 12) TO (2017, 01);
CREATE TABLE measurement_ym_y2017m01
PARTITION OF measurement_year_month
FOR VALUES FROM (2017, 01) TO (2017, 02);
</programlisting></para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Create partition of a list partitioned table:
<programlisting>
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
CREATE TABLE cities_ab
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
PARTITION OF cities (
CONSTRAINT city_id_nonzero CHECK (city_id != 0)
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
) FOR VALUES IN ('a', 'b');
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</programlisting></para>
<para>
Create partition of a list partitioned table that is itself further
partitioned and then add a partition to it:
<programlisting>
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
CREATE TABLE cities_ab
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
PARTITION OF cities (
CONSTRAINT city_id_nonzero CHECK (city_id != 0)
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
) FOR VALUES IN ('a', 'b') PARTITION BY RANGE (population);
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
CREATE TABLE cities_ab_10000_to_100000
PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000);
Fix a whitespace issue with the man pages There is what may actually be a mistake in our markup. The problem is in a situation like <para> <command>FOO</command> is ... there is strictly speaking a line break before "FOO". In the HTML output, this does not appear to be a problem, but in the man page output, this shows up, so you get double blank lines at odd places. So far, we have attempted to work around this with an XSL hack, but that causes other problems, such as creating run-ins in places like <acronym>SQL</acronym> <command>COPY</command> So fix the problem properly by removing the extra whitespace. I only fixed the problems that affect the man page output, not all the places.
2011-08-07 09:49:45 +02:00
</programlisting></para>
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
<para>
Create partitions of a hash partitioned table:
<programlisting>
CREATE TABLE orders_p1 PARTITION OF orders
FOR VALUES WITH (MODULUS 4, REMAINDER 0);
CREATE TABLE orders_p2 PARTITION OF orders
FOR VALUES WITH (MODULUS 4, REMAINDER 1);
CREATE TABLE orders_p3 PARTITION OF orders
FOR VALUES WITH (MODULUS 4, REMAINDER 2);
CREATE TABLE orders_p4 PARTITION OF orders
FOR VALUES WITH (MODULUS 4, REMAINDER 3);
</programlisting></para>
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
<para>
Create a default partition:
<programlisting>
CREATE TABLE cities_partdef
PARTITION OF cities DEFAULT;
</programlisting></para>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
</refsect1>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs. Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
2020-05-11 20:15:49 +02:00
<refsect1 id="sql-createtable-compatibility" xreflabel="Compatibility">
<title>Compatibility</title>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Make an editorial pass over the reference pages.
2005-11-01 22:09:51 +01:00
The <command>CREATE TABLE</command> command conforms to the
<acronym>SQL</acronym> standard, with exceptions listed below.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
<refsect2>
<title>Temporary Tables</title>
Minor updates for release. Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml (the emacs parser) to handle parsing.
1999-06-14 09:37:05 +02:00
<para>
Clarify description of our deviation from standard for temp tables, per suggestion from Mike Sykes.
2003-04-14 17:24:46 +02:00
Although the syntax of <literal>CREATE TEMPORARY TABLE</literal>
When a TIMESTAMP, TIME, or INTERVAL precision is specified larger than our implementation limits, do not issue an ERROR; instead issue a NOTICE and use the max supported value. Per pgsql-general discussion of 28-Apr, this is needed to allow easy porting from pre-7.3 releases where the limits were higher. Unrelated change in same area: accept GLOBAL TEMP/TEMPORARY as a synonym for TEMPORARY, as per pgsql-hackers discussion of 15-Apr. We previously rejected it, but that was based on a misreading of the spec --- SQL92's GLOBAL temp tables are really closer to what we have than their LOCAL ones.
2003-05-04 02:03:55 +02:00
resembles that of the SQL standard, the effect is not the same. In the
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
standard,
Another try at correctly explaining the difference between Postgres and SQL92 temp tables. Possibly I got it right this time.
2003-04-14 20:08:58 +02:00
temporary tables are defined just once and automatically exist (starting
with empty contents) in every session that needs them.
<productname>PostgreSQL</productname> instead
Clarify description of our deviation from standard for temp tables, per suggestion from Mike Sykes.
2003-04-14 17:24:46 +02:00
requires each session to issue its own <literal>CREATE TEMPORARY
Another try at correctly explaining the difference between Postgres and SQL92 temp tables. Possibly I got it right this time.
2003-04-14 20:08:58 +02:00
TABLE</literal> command for each temporary table to be used. This allows
different sessions to use the same temporary table name for different
More editing of reference pages.
2003-04-22 12:08:08 +02:00
purposes, whereas the standard's approach constrains all instances of a
Another try at correctly explaining the difference between Postgres and SQL92 temp tables. Possibly I got it right this time.
2003-04-14 20:08:58 +02:00
given temporary table name to have the same table structure.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<para>
When a TIMESTAMP, TIME, or INTERVAL precision is specified larger than our implementation limits, do not issue an ERROR; instead issue a NOTICE and use the max supported value. Per pgsql-general discussion of 28-Apr, this is needed to allow easy porting from pre-7.3 releases where the limits were higher. Unrelated change in same area: accept GLOBAL TEMP/TEMPORARY as a synonym for TEMPORARY, as per pgsql-hackers discussion of 15-Apr. We previously rejected it, but that was based on a misreading of the spec --- SQL92's GLOBAL temp tables are really closer to what we have than their LOCAL ones.
2003-05-04 02:03:55 +02:00
The standard's definition of the behavior of temporary tables is
More editing of reference pages.
2003-04-22 12:08:08 +02:00
widely ignored. <productname>PostgreSQL</productname>'s behavior
on this point is similar to that of several other SQL databases.
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Another try at correctly explaining the difference between Postgres and SQL92 temp tables. Possibly I got it right this time.
2003-04-14 20:08:58 +02:00
<para>
Deprecate use of GLOBAL and LOCAL in temp table creation. Aside from adjusting the documentation to say that these are deprecated, we now report a warning (not an error) for use of GLOBAL, since it seems fairly likely that we might change that to request SQL-spec-compliant temp table behavior in the foreseeable future. Although our handling of LOCAL is equally nonstandard, there is no evident interest in ever implementing SQL modules, and furthermore some other products interpret LOCAL as behaving the same way we do. So no expectation of change and no warning for LOCAL; but it still seems a good idea to deprecate writing it. Noah Misch
2012-06-13 23:48:42 +02:00
The SQL standard also distinguishes between global and local temporary
Fix description of SQL-standard meaning of CREATE LOCAL TEMP TABLE. I had this slightly wrong, as noted by Noah Misch.
2012-06-14 00:47:53 +02:00
tables, where a local temporary table has a separate set of contents for
each SQL module within each session, though its definition is still shared
across sessions. Since <productname>PostgreSQL</productname> does not
support SQL modules, this distinction is not relevant in
<productname>PostgreSQL</productname>.
Deprecate use of GLOBAL and LOCAL in temp table creation. Aside from adjusting the documentation to say that these are deprecated, we now report a warning (not an error) for use of GLOBAL, since it seems fairly likely that we might change that to request SQL-spec-compliant temp table behavior in the foreseeable future. Although our handling of LOCAL is equally nonstandard, there is no evident interest in ever implementing SQL modules, and furthermore some other products interpret LOCAL as behaving the same way we do. So no expectation of change and no warning for LOCAL; but it still seems a good idea to deprecate writing it. Noah Misch
2012-06-13 23:48:42 +02:00
</para>
<para>
When a TIMESTAMP, TIME, or INTERVAL precision is specified larger than our implementation limits, do not issue an ERROR; instead issue a NOTICE and use the max supported value. Per pgsql-general discussion of 28-Apr, this is needed to allow easy porting from pre-7.3 releases where the limits were higher. Unrelated change in same area: accept GLOBAL TEMP/TEMPORARY as a synonym for TEMPORARY, as per pgsql-hackers discussion of 15-Apr. We previously rejected it, but that was based on a misreading of the spec --- SQL92's GLOBAL temp tables are really closer to what we have than their LOCAL ones.
2003-05-04 02:03:55 +02:00
For compatibility's sake, <productname>PostgreSQL</productname> will
accept the <literal>GLOBAL</literal> and <literal>LOCAL</literal> keywords
Deprecate use of GLOBAL and LOCAL in temp table creation. Aside from adjusting the documentation to say that these are deprecated, we now report a warning (not an error) for use of GLOBAL, since it seems fairly likely that we might change that to request SQL-spec-compliant temp table behavior in the foreseeable future. Although our handling of LOCAL is equally nonstandard, there is no evident interest in ever implementing SQL modules, and furthermore some other products interpret LOCAL as behaving the same way we do. So no expectation of change and no warning for LOCAL; but it still seems a good idea to deprecate writing it. Noah Misch
2012-06-13 23:48:42 +02:00
in a temporary table declaration, but they currently have no effect.
Use of these keywords is discouraged, since future versions of
<productname>PostgreSQL</productname> might adopt a more
standard-compliant interpretation of their meaning.
Another try at correctly explaining the difference between Postgres and SQL92 temp tables. Possibly I got it right this time.
2003-04-14 20:08:58 +02:00
</para>
Clarify description of our deviation from standard for temp tables, per suggestion from Mike Sykes.
2003-04-14 17:24:46 +02:00
<para>
Minor copy-editing.
2003-04-14 17:40:02 +02:00
The <literal>ON COMMIT</literal> clause for temporary tables
More editing of reference pages.
2003-04-22 12:08:08 +02:00
also resembles the SQL standard, but has some differences.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If the <literal>ON COMMIT</literal> clause is omitted, SQL specifies that the
default behavior is <literal>ON COMMIT DELETE ROWS</literal>. However, the
Clarify description of our deviation from standard for temp tables, per suggestion from Mike Sykes.
2003-04-14 17:24:46 +02:00
default behavior in <productname>PostgreSQL</productname> is
<literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT
More editing of reference pages.
2003-04-22 12:08:08 +02:00
DROP</literal> option does not exist in SQL.
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</refsect2>
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
<refsect2>
doc: Clean up title case use Note: Following existing practice, titles of formalpara and step are not titlecased.
2019-09-08 10:26:35 +02:00
<title>Non-Deferred Uniqueness Constraints</title>
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
When a <literal>UNIQUE</literal> or <literal>PRIMARY KEY</literal> constraint is
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
not deferrable, <productname>PostgreSQL</productname> checks for
uniqueness immediately whenever a row is inserted or modified.
The SQL standard says that uniqueness should be enforced only at
the end of the statement; this makes a difference when, for example,
a single command updates multiple key values. To obtain
standard-compliant behavior, declare the constraint as
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>DEFERRABLE</literal> but not deferred (i.e., <literal>INITIALLY
IMMEDIATE</literal>). Be aware that this can be significantly slower than
Support deferrable uniqueness constraints. The current implementation fires an AFTER ROW trigger for each tuple that looks like it might be non-unique according to the index contents at the time of insertion. This works well as long as there aren't many conflicts, but won't scale to massive unique-key reassignments. Improving that case is a TODO item. Dean Rasheed
2009-07-29 22:56:21 +02:00
immediate uniqueness checking.
</para>
</refsect2>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<refsect2>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<title>Column Check Constraints</title>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The SQL standard says that <literal>CHECK</literal> column constraints
can only refer to the column they apply to; only <literal>CHECK</literal>
Update reference 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".
2007-02-01 00:26:05 +01:00
table constraints can refer to multiple columns.
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<productname>PostgreSQL</productname> does not enforce this
restriction; it treats column and table check constraints alike.
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
</para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</refsect2>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
<refsect2>
<title><literal>EXCLUDE</literal> Constraint</title>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>EXCLUDE</literal> constraint type is a
Add exclusion constraints, which generalize the concept of uniqueness to support any indexable commutative operator, not just equality. Two rows violate the exclusion constraint if "row1.col OP row2.col" is TRUE for each of the columns in the constraint. Jeff Davis, reviewed by Robert Haas
2009-12-07 06:22:23 +01:00
<productname>PostgreSQL</productname> extension.
</para>
</refsect2>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
<refsect2>
Doc: mention foreign keys can reference unique indexes We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-29 22:15:17 +01:00
<title>Foreign Key Constraints</title>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
<para>
Doc: mention foreign keys can reference unique indexes We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-29 22:15:17 +01:00
The ability to specify column lists in the foreign key actions
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
<literal>SET DEFAULT</literal> and <literal>SET NULL</literal> is a
<productname>PostgreSQL</productname> extension.
</para>
Doc: mention foreign keys can reference unique indexes We seem to have only documented a foreign key can reference the columns of a primary key or unique constraint. Here we adjust the documentation to mention columns in a non-partial unique index can be mentioned too. The header comment for transformFkeyCheckAttrs() also didn't mention unique indexes, so fix that too. In passing make that header comment reflect reality in the various other aspects where it deviated from it. Bug: 18295 Reported-by: Gilles PARC Author: Laurenz Albe, David Rowley Discussion: https://www.postgresql.org/message-id/18295-0ed0fac5c9f7b17b%40postgresql.org Backpatch-through: 12
2024-01-29 22:15:17 +01:00
<para>
It is a <productname>PostgreSQL</productname> extension that a
foreign key constraint may reference columns of a unique index instead of
columns of a primary key or unique constraint.
</para>
Allow specifying column list for foreign key ON DELETE SET actions Extend the foreign key ON DELETE actions SET NULL and SET DEFAULT by allowing the specification of a column list, like CREATE TABLE posts ( ... FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL (author_id) ); If a column list is specified, only those columns are set to null/default, instead of all the columns in the foreign-key constraint. This is useful for multitenant or sharded schemas, where the tenant or shard ID is included in the primary key of all tables but shouldn't be set to null. Author: Paul Martinez <paulmtz@google.com> Discussion: https://www.postgresql.org/message-id/flat/CACqFVBZQyMYJV=njbSMxf+rbDHpx=W=B7AEaMKn8dWn9OZJY7w@mail.gmail.com
2021-12-08 11:09:44 +01:00
</refsect2>
More editing of reference pages.
2003-04-22 12:08:08 +02:00
<refsect2>
<title><literal>NULL</literal> <quote>Constraint</quote></title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>NULL</literal> <quote>constraint</quote> (actually a
More editing of reference pages.
2003-04-22 12:08:08 +02:00
non-constraint) is a <productname>PostgreSQL</productname>
extension to the SQL standard that is included for compatibility with some
other database systems (and for symmetry with the <literal>NOT
NULL</literal> constraint). Since it is the default for any
column, its presence is simply noise.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</refsect2>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
<refsect2>
<title>Constraint Naming</title>
<para>
The SQL standard says that table and domain constraints must have names
that are unique across the schema containing the table or domain.
<productname>PostgreSQL</productname> is laxer: it only requires
constraint names to be unique across the constraints attached to a
particular table or domain. However, this extra freedom does not exist
for index-based constraints (<literal>UNIQUE</literal>,
<literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal>
constraints), because the associated index is named the same as the
constraint, and index names must be unique across all relations within
the same schema.
</para>
</refsect2>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<refsect2>
<title>Inheritance</title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
Multiple inheritance via the <literal>INHERITS</literal> clause is
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
a <productname>PostgreSQL</productname> language extension.
Make an editorial pass over the reference pages.
2005-11-01 22:09:51 +01:00
SQL:1999 and later define single inheritance using a
different syntax and different semantics. SQL:1999-style
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
inheritance is not yet supported by
<productname>PostgreSQL</productname>.
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</para>
</refsect2>
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
Document that zero-column tables are allowed (and non-standard).
2002-12-16 20:08:25 +01:00
<refsect2>
doc: Clean up title case use Note: Following existing practice, titles of formalpara and step are not titlecased.
2019-09-08 10:26:35 +02:00
<title>Zero-Column Tables</title>
Document that zero-column tables are allowed (and non-standard).
2002-12-16 20:08:25 +01:00
<para>
<productname>PostgreSQL</productname> allows a table of no columns
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
to be created (for example, <literal>CREATE TABLE foo();</literal>). This
Document that zero-column tables are allowed (and non-standard).
2002-12-16 20:08:25 +01:00
is an extension from the SQL standard, which does not allow zero-column
tables. Zero-column tables are not in themselves very useful, but
disallowing them creates odd special cases for <command>ALTER TABLE
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
DROP COLUMN</command>, so it seems cleaner to ignore this spec restriction.
Document that zero-column tables are allowed (and non-standard).
2002-12-16 20:08:25 +01:00
</para>
</refsect2>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
<refsect2>
<title>Multiple Identity Columns</title>
<para>
<productname>PostgreSQL</productname> allows a table to have more than one
identity column. The standard specifies that a table can have at most one
identity column. This is relaxed mainly to give more flexibility for
doing schema changes or migrations. Note that
the <command>INSERT</command> command supports only one override clause
that applies to the entire statement, so having multiple identity columns
with different behaviors is not well supported.
</para>
</refsect2>
Generated columns This is an SQL-standard feature that allows creating columns that are computed from expressions rather than assigned, similar to a view or materialized view but on a column basis. This implements one kind of generated column: stored (computed on write). Another kind, virtual (computed on read), is planned for the future, and some room is left for it. Reviewed-by: Michael Paquier <michael@paquier.xyz> Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/b151f851-4019-bdb1-699e-ebab07d2f40a@2ndquadrant.com
2019-03-30 08:13:09 +01:00
<refsect2>
<title>Generated Columns</title>
<para>
The option <literal>STORED</literal> is not standard but is also used by
other SQL implementations. The SQL standard does not specify the storage
of generated columns.
</para>
</refsect2>
Improve documentation about CREATE TABLE ... LIKE. The docs failed to explain that LIKE INCLUDING INDEXES would not preserve the names of indexes and associated constraints. Also, it wasn't mentioned that EXCLUDE constraints would be copied by this option. The latter oversight seems enough of a documentation bug to justify back-patching. In passing, do some minor copy-editing in the same area, and add an entry for LIKE under "Compatibility", since it's not exactly a faithful implementation of the standard's feature. Discussion: <20160728151154.AABE64016B@smtp.hushmail.com>
2016-07-28 19:26:58 +02:00
<refsect2>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<title><literal>LIKE</literal> Clause</title>
Improve documentation about CREATE TABLE ... LIKE. The docs failed to explain that LIKE INCLUDING INDEXES would not preserve the names of indexes and associated constraints. Also, it wasn't mentioned that EXCLUDE constraints would be copied by this option. The latter oversight seems enough of a documentation bug to justify back-patching. In passing, do some minor copy-editing in the same area, and add an entry for LIKE under "Compatibility", since it's not exactly a faithful implementation of the standard's feature. Discussion: <20160728151154.AABE64016B@smtp.hushmail.com>
2016-07-28 19:26:58 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
While a <literal>LIKE</literal> clause exists in the SQL standard, many of the
Improve documentation about CREATE TABLE ... LIKE. The docs failed to explain that LIKE INCLUDING INDEXES would not preserve the names of indexes and associated constraints. Also, it wasn't mentioned that EXCLUDE constraints would be copied by this option. The latter oversight seems enough of a documentation bug to justify back-patching. In passing, do some minor copy-editing in the same area, and add an entry for LIKE under "Compatibility", since it's not exactly a faithful implementation of the standard's feature. Discussion: <20160728151154.AABE64016B@smtp.hushmail.com>
2016-07-28 19:26:58 +02:00
options that <productname>PostgreSQL</productname> accepts for it are not
in the standard, and some of the standard's options are not implemented
by <productname>PostgreSQL</productname>.
</para>
</refsect2>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<refsect2>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<title><literal>WITH</literal> Clause</title>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>WITH</literal> clause is a <productname>PostgreSQL</productname>
Remove WITH OIDS support, change oid catalog column visibility. Previously tables declared WITH OIDS, including a significant fraction of the catalog tables, stored the oid column not as a normal column, but as part of the tuple header. This special column was not shown by default, which was somewhat odd, as it's often (consider e.g. pg_class.oid) one of the more important parts of a row. Neither pg_dump nor COPY included the contents of the oid column by default. The fact that the oid column was not an ordinary column necessitated a significant amount of special case code to support oid columns. That already was painful for the existing, but upcoming work aiming to make table storage pluggable, would have required expanding and duplicating that "specialness" significantly. WITH OIDS has been deprecated since 2005 (commit ff02d0a05280e0). Remove it. Removing includes: - CREATE TABLE and ALTER TABLE syntax for declaring the table to be WITH OIDS has been removed (WITH (oids[ = true]) will error out) - pg_dump does not support dumping tables declared WITH OIDS and will issue a warning when dumping one (and ignore the oid column). - restoring an pg_dump archive with pg_restore will warn when restoring a table with oid contents (and ignore the oid column) - COPY will refuse to load binary dump that includes oids. - pg_upgrade will error out when encountering tables declared WITH OIDS, they have to be altered to remove the oid column first. - Functionality to access the oid of the last inserted row (like plpgsql's RESULT_OID, spi's SPI_lastoid, ...) has been removed. The syntax for declaring a table WITHOUT OIDS (or WITH (oids = false) for CREATE TABLE) is still supported. While that requires a bit of support code, it seems unnecessary to break applications / dumps that do not use oids, and are explicit about not using them. The biggest user of WITH OID columns was postgres' catalog. This commit changes all 'magic' oid columns to be columns that are normally declared and stored. To reduce unnecessary query breakage all the newly added columns are still named 'oid', even if a table's column naming scheme would indicate 'reloid' or such. This obviously requires adapting a lot code, mostly replacing oid access via HeapTupleGetOid() with access to the underlying Form_pg_*->oid column. The bootstrap process now assigns oids for all oid columns in genbki.pl that do not have an explicit value (starting at the largest oid previously used), only oids assigned later by oids will be above FirstBootstrapObjectId. As the oid column now is a normal column the special bootstrap syntax for oids has been removed. Oids are not automatically assigned during insertion anymore, all backend code explicitly assigns oids with GetNewOidWithIndex(). For the rare case that insertions into the catalog via SQL are called for the new pg_nextoid() function can be used (which only works on catalog tables). The fact that oid columns on system tables are now normal columns means that they will be included in the set of columns expanded by * (i.e. SELECT * FROM pg_class will now include the table's oid, previously it did not). It'd not technically be hard to hide oid column by default, but that'd mean confusing behavior would either have to be carried forward forever, or it'd cause breakage down the line. While it's not unlikely that further adjustments are needed, the scope/invasiveness of the patch makes it worthwhile to get merge this now. It's painful to maintain externally, too complicated to commit after the code code freeze, and a dependency of a number of other patches. Catversion bump, for obvious reasons. Author: Andres Freund, with contributions by John Naylor Discussion: https://postgr.es/m/20180930034810.ywp2c7awz7opzcfr@alap3.anarazel.de
2018-11-21 00:36:57 +01:00
extension; storage parameters are not in the standard.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
</refsect2>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
<refsect2>
Spell checker run
2004-12-13 19:05:10 +01:00
<title>Tablespaces</title>
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
<para>
The <productname>PostgreSQL</productname> concept of tablespaces is not
Spell checker run
2004-12-13 19:05:10 +01:00
part of the standard. Hence, the clauses <literal>TABLESPACE</literal>
and <literal>USING INDEX TABLESPACE</literal> are extensions.
Tablespaces. Alternate database locations are dead, long live tablespaces. There are various things left to do: contrib dbsize and oid2name modules need work, and so does the documentation. Also someone should think about COMMENT ON TABLESPACE and maybe RENAME TABLESPACE. Also initlocation is dead, it just doesn't know it yet. Gavin Sherry and Tom Lane.
2004-06-18 08:14:31 +02:00
</para>
</refsect2>
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
<refsect2>
<title>Typed Tables</title>
<para>
Typed tables implement a subset of the SQL standard. According to
the standard, a typed table has columns corresponding to the
underlying composite type as well as one other column that is
Doc: Improve wording of multiple places in documentation This has been found during its translation. Author: Liudmila Mantrova Discussion: https://postgr.es/m/CAEkD-mDJHV3bhgezu3MUafJLoAKsOOT86+wHukKU8_NeiJYhLQ@mail.gmail.com Backpatch-through: 12
2019-08-20 05:36:31 +02:00
the <quote>self-referencing column</quote>.
<productname>PostgreSQL</productname> does not support self-referencing
columns explicitly.
Type table feature This adds the CREATE TABLE name OF type command, per SQL standard.
2010-01-29 00:21:13 +01:00
</para>
</refsect2>
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<refsect2>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<title><literal>PARTITION BY</literal> Clause</title>
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>PARTITION BY</literal> clause is a
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<productname>PostgreSQL</productname> extension.
</para>
</refsect2>
<refsect2>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<title><literal>PARTITION OF</literal> Clause</title>
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>PARTITION OF</literal> clause is a
Improve CREATE TABLE documentation of partitioning Amit Langote, with corrections by me
2017-02-10 09:59:37 +01:00
<productname>PostgreSQL</productname> extension.
</para>
</refsect2>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</refsect1>
Remove not-really-standard implementation of CREATE TABLE's UNDER clause, and revert documentation to describe the existing INHERITS clause instead, per recent discussion in pghackers. Also fix implementation of SQL_inheritance SET variable: it is not cool to look at this var during the initial parsing phase, only during parse_analyze(). See recent bug report concerning misinterpretation of date constants just after a SET TIMEZONE command. gram.y really has to be an invariant transformation of the query string to a raw parsetree; anything that can vary with time must be done during parse analysis.
2001-01-05 07:34:23 +01:00
Make OIDs optional, per discussions in pghackers. WITH OIDS is still the default, but OIDS are removed from many system catalogs that don't need them. Some interesting side effects: TOAST pointers are 20 bytes not 32 now; pg_description has a three-column key instead of one. Bugs fixed in passing: BINARY cursors work again; pg_class.relhaspkey has some usefulness; pg_dump dumps comments on indexes, rules, and triggers in a valid order. initdb forced.
2001-08-10 20:57:42 +02:00
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
<refsect1>
<title>See Also</title>
<simplelist type="inline">
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<member><xref linkend="sql-altertable"/></member>
<member><xref linkend="sql-droptable"/></member>
<member><xref linkend="sql-createtableas"/></member>
<member><xref linkend="sql-createtablespace"/></member>
<member><xref linkend="sql-createtype"/></member>
Make the CREATE TABLE ref page more readable and update some information.
2001-10-22 20:14:47 +02:00
</simplelist>
First version of files from Oliver Elphick.
1998-07-14 05:47:34 +02:00
</refsect1>
</refentry>