From c6f8d17d04d1bf1ddcbe0f2293d8f1462a1379f4 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 8 Dec 2020 13:09:47 -0500 Subject: [PATCH] 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 --- doc/src/sgml/ref/create_table.sgml | 58 ++++++++++++++++++------------ 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 281f649145..9300b71e75 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -877,15 +877,17 @@ WITH ( MODULUS numeric_literal, REM UNIQUE (column constraint) UNIQUE ( column_name [, ... ] ) - INCLUDE ( column_name [, ...]) (table constraint) + INCLUDE ( column_name [, ...]) (table constraint) The UNIQUE constraint specifies that a group of one or more columns of a table can contain - only unique values. The behavior of the unique table constraint - is the same as that for column constraints, with the additional - capability to span multiple columns. + 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. @@ -894,10 +896,10 @@ WITH ( MODULUS numeric_literal, REM - Each unique table constraint must name a set of columns that is + Each unique constraint should name a set of columns that is different from the set of columns named by any other unique or - primary key constraint defined for the table. (Otherwise it - would just be the same constraint listed twice.) + primary key constraint defined for the table. (Otherwise, redundant + unique constraints will be discarded.) @@ -910,10 +912,15 @@ WITH ( MODULUS numeric_literal, REM Adding a unique constraint will automatically create a unique btree index on the column or group of columns used in the constraint. - The optional clause INCLUDE adds to that index - one or more columns on which the uniqueness is not enforced. - Note that although the constraint is not enforced on the included columns, - it still depends on them. Consequently, some operations on these columns + + + + The optional INCLUDE clause adds to that index + one or more columns that are simply payload: 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., DROP COLUMN) can cause cascaded constraint and index deletion. @@ -923,7 +930,7 @@ WITH ( MODULUS numeric_literal, REM PRIMARY KEY (column constraint) PRIMARY KEY ( column_name [, ... ] ) - INCLUDE ( column_name [, ...]) (table constraint) + INCLUDE ( column_name [, ...]) (table constraint) The PRIMARY KEY constraint specifies that a column or @@ -941,27 +948,34 @@ WITH ( MODULUS numeric_literal, REM PRIMARY KEY enforces the same data constraints as - a combination of UNIQUE and NOT NULL, but + a combination of UNIQUE and NOT + NULL. However, 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. - PRIMARY KEY constraints share the restrictions that - UNIQUE constraints have when placed on partitioned - tables. + When placed on a partitioned table, PRIMARY KEY + constraints share the restrictions previously decribed + for UNIQUE constraints. Adding a PRIMARY KEY constraint will automatically create a unique btree index on the column or group of columns used in the - constraint. The optional INCLUDE clause allows a list - of columns to be specified which will be included in the non-key portion - of the index. Although uniqueness is not enforced on the included columns, - the constraint still depends on them. Consequently, some operations on the - included columns (e.g., DROP COLUMN) can cause cascaded - constraint and index deletion. + constraint. + + + + The optional INCLUDE clause adds to that index + one or more columns that are simply payload: 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., DROP COLUMN) can cause cascaded constraint and + index deletion.