diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b3a92b9aabc..66510ee0315 100644
--- 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 .
+ identity column feature, described at .
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 77790f2e4b2..4044f0908f0 100644
--- 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