doc: Add Identity Column section under Data Definition chapter

This seems to be missing since identity column support was added.  Add
the same.  This gives a place to document various pieces of
information in one place that are currently distributed over several
command reference pages or just not documented (e.g., inheritance
behavior).

Author: Ashutosh Bapat 
Author: Peter Eisentraut 
Discussion: https://www.postgresql.org/message-id/flat/CAExHW5uOykuTC+C6R1yDSp=o8Q83jr8xJdZxgPkxfZ1Ue5RRGg@mail.gmail.com

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b3a92b9aabc906b4499d933d7da939092297e4f0..66510ee03155389b77402b53a54a35dd472191f1 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -955,7 +955,7 @@ FROM generate_series(-3.5, 3.5, 1) as x;
      
       This section describes a PostgreSQL-specific way to create an
       autoincrementing column.  Another way is to use the SQL-standard
-      identity column feature, described at sql-createtable"/>.
+      identity column feature, described at ddl-identity-columns"/>.
      
     
 

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 77790f2e4b2f7aa799e655de24ffca6687952181..4044f0908f098f40ca0732f511825c9219f20540 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -233,6 +233,116 @@ CREATE TABLE products (
   
  
 
+ 
+  Identity Columns
+
+  
+   identity column
+  
+
+  
+   An identity column is a special column that is generated automatically from
+   an implicit sequence.  It can be used to generate key values.
+  
+
+  
+   To create an identity column, use the GENERATED ...
+   AS IDENTITY clause in CREATE TABLE, for example:
+
+CREATE TABLE people (
+    id bigint GENERATED ALWAYS AS IDENTITY,
+    ...,
+);
+
+   or alternatively
+
+CREATE TABLE people (
+    id bigint GENERATED BY DEFAULT IDENTITY,
+    ...,
+);
+
+   See  for more details.
+  
+
+  
+   If an INSERT command is executed on the table with the
+   identity column and no value is explicitly specified for the identity
+   column, then a value generated by the implicit sequence is inserted.  For
+   example, with the above definitions and assuming additional appropriate
+   columns, writing
+
+INSERT INTO people (name, address) VALUE ('A', 'foo');
+INSERT INTO people (name, address) VALUE ('B', 'bar');
+
+   would generate values for the id column starting at 1
+   and result in the following table data:
+
+ id | name | address
+----+------+---------
+  1 | A    | foo
+  2 | B    | bar
+
+   Alternatively, the keyword DEFAULT can be specified in
+   place of a value to explicitly request the sequence-generated value, like
+
+INSERT INTO people (id, name, address) VALUE (DEFAULT, 'C', 'baz');
+
+   Similarly, the keyword DEFAULT can be used in
+   UPDATE commands.
+  
+
+  
+   Thus, in many ways, an identity column behaves like a column with a default
+   value.
+  
+
+  
+   The clauses ALWAYS and BY DEFAULT in
+   the column definition determine how explicitly user-specified values are
+   handled in INSERT and UPDATE
+   commands.  In an INSERT command, if
+   ALWAYS is selected, a user-specified value is only
+   accepted if the INSERT statement specifies
+   OVERRIDING SYSTEM VALUE.  If BY
+   DEFAULT is selected, then the user-specified value takes
+   precedence.  Thus, using BY DEFAULT results in a
+   behavior more similar to default values, where the default value can be
+   overridden by an explicit value, whereas ALWAYS provides
+   some more protection against accidentally inserting an explicit value.
+  
+
+  
+   The data type of an identity column must be one of the data types supported
+   by sequences.  (See .)  The properties
+   of the associated sequence may be specified when creating an identity
+   column (see ) or changed afterwards (see
+   ).
+  
+
+  
+   An identity column is automatically marked as NOT NULL.
+   An identity column, however, does not guarantee uniqueness.  (A sequence
+   normally returns unique values, but a sequence could be reset, or values
+   could be inserted manually into the identity column, as discussed above.)
+   Uniqueness would need to be enforced using a PRIMARY KEY
+   or UNIQUE constraint.
+  
+
+  
+   In table inheritance hierarchies, identity columns and their properties in
+   a child table are independent of those in its parent tables.  A child table
+   does not inherit identity columns or their properties automatically from
+   the parent. During INSERT or UPDATE,
+   a column is treated as an identity column if that column is an identity
+   column in the table named in the statement, and the corresponding identity
+   properties are applied.
+  
+
+  
+   Identity columns are currently not supported for partitioned tables.
+  
+ 
+
  
   Generated Columns