diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 9009addb9c..dfbc65d327 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -78,9 +78,9 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[ CONSTRAINT constraint_name ]
{ CHECK ( expression ) [ NO INHERIT ] |
UNIQUE ( column_name [, ... ] ) index_parameters |
- PRIMARY KEY ( column_name [, ... ] ) index_parameters |
+ PRIMARY KEY ( column_name [, ... ] [, temporal_inverval WITHOUT OVERLAPS ] ) index_parameters |
EXCLUDE [ USING index_method ] ( exclude_element WITH operator [, ... ] ) index_parameters [ WHERE ( predicate ) ] |
- FOREIGN KEY ( column_name [, ... ] ) REFERENCES reftable [ ( refcolumn [, ... ] ) ]
+ FOREIGN KEY ( column_name [, ... ] [, PERIOD temporal_interval ] ) REFERENCES reftable [ ( refcolumn [, ... ] [, PERIOD temporal_interval ] ) ]
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
@@ -105,6 +105,11 @@ WITH ( MODULUS numeric_literal, REM
exclude_element in an EXCLUDE constraint is:
{ column_name | ( expression ) } [ opclass ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
+
+temporal_interval in a PRIMARY KEY or FOREIGN KEY constraint is:
+
+range_column_name
+
@@ -909,7 +914,8 @@ WITH ( MODULUS numeric_literal, REM
PRIMARY KEY (column constraint)
- PRIMARY KEY ( column_name [, ... ] )
+ PRIMARY KEY ( column_name [, ... ]
+ [, temporal_interval WITHOUT OVERLAPS ] )
INCLUDE ( column_name [, ...]) (table constraint)
@@ -942,7 +948,7 @@ WITH ( MODULUS numeric_literal, REM
Adding a PRIMARY KEY constraint will automatically
- create a unique btree index on the column or group of columns used in the
+ create a unique btree (or GiST if temporal) 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,
@@ -950,6 +956,24 @@ WITH ( MODULUS numeric_literal, REM
included columns (e.g. DROP COLUMN) can cause cascaded
constraint and index deletion.
+
+
+ A PRIMARY KEY with a WITHOUT OVERLAPS option
+ is a temporal primary key.
+ The WITHOUT OVERLAPS column
+ must be a range type and is used to constrain the record's applicability
+ to just that range (usually a range of dates or timestamps).
+ The main part of the primary key may be repeated elsewhere in the table,
+ as long as records with the same key don't overlap in the
+ WITHOUT OVERLAPS column.
+
+
+
+ A temporal PRIMARY KEY is enforced with an
+ EXCLUDE constraint rather than a UNIQUE
+ constraint, backed by a GiST index. You may need to install the
+ extension to create temporal primary keys.
+
@@ -1006,8 +1030,8 @@ WITH ( MODULUS numeric_literal, REM
REFERENCES reftable [ ( refcolumn ) ] [ MATCH matchtype ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ] (column constraint)
- FOREIGN KEY ( column_name [, ... ] )
- REFERENCES reftable [ ( refcolumn [, ... ] ) ]
+ FOREIGN KEY ( column_name [, ... ] [, PERIOD temporal_interval ] )
+ REFERENCES reftable [ ( refcolumn [, ... ] [, PERIOD temporal_interval ] ) ]
[ MATCH matchtype ]
[ ON DELETE referential_action ]
[ ON UPDATE referential_action ]
@@ -1018,11 +1042,29 @@ WITH ( MODULUS numeric_literal, REM
These clauses specify a foreign key constraint, which requires
that a group of one or more columns of the new table must only
contain values that match values in the referenced
- column(s) of some row of the referenced table. If the refcolumn list is omitted, the
primary key of the reftable
is used. The referenced columns must be the columns of a non-deferrable
- unique or primary key constraint in the referenced table. The user
+ unique or primary key constraint in the referenced table.
+
+
+
+ If the last column is marked with PERIOD,
+ it must be a range column, and the referenced table
+ must have a temporal primary key.
+ The non-PERIOD columns are treated normally
+ (and there must be at least one of them),
+ but the PERIOD column is not compared for equality.
+ Instead the constraint is considered satisfied
+ if the referenced table has matching records whose combined ranges completely cover
+ the referencing record.
+ In other words, the reference must have a referent for its entire duration.
+
+
+
+ The user
must have REFERENCES permission on the referenced table
(either the whole table, or the specific referenced columns). The
addition of a foreign key constraint requires a