Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit a37bb7c

Browse files
committed
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 <ashutosh.bapat.oss@gmail.com> Author: Peter Eisentraut <peter@eisentraut.org> Discussion: https://www.postgresql.org/message-id/flat/CAExHW5uOykuTC+C6R1yDSp=o8Q83jr8xJdZxgPkxfZ1Ue5RRGg@mail.gmail.com
1 parent d22d98c commit a37bb7c

File tree

2 files changed

+111
-1
lines changed

2 files changed

+111
-1
lines changed

doc/src/sgml/datatype.sgml

+1-1
Original file line numberDiff line numberDiff line change
@@ -955,7 +955,7 @@ FROM generate_series(-3.5, 3.5, 1) as x;
955955
<para>
956956
This section describes a PostgreSQL-specific way to create an
957957
autoincrementing column. Another way is to use the SQL-standard
958-
identity column feature, described at <xref linkend="sql-createtable"/>.
958+
identity column feature, described at <xref linkend="ddl-identity-columns"/>.
959959
</para>
960960
</note>
961961

doc/src/sgml/ddl.sgml

+110
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,116 @@ CREATE TABLE products (
233233
</para>
234234
</sect1>
235235

236+
<sect1 id="ddl-identity-columns">
237+
<title>Identity Columns</title>
238+
239+
<indexterm zone="ddl-identity-columns">
240+
<primary>identity column</primary>
241+
</indexterm>
242+
243+
<para>
244+
An identity column is a special column that is generated automatically from
245+
an implicit sequence. It can be used to generate key values.
246+
</para>
247+
248+
<para>
249+
To create an identity column, use the <literal>GENERATED ...
250+
AS IDENTITY</literal> clause in <command>CREATE TABLE</command>, for example:
251+
<programlisting>
252+
CREATE TABLE people (
253+
id bigint <emphasis>GENERATED ALWAYS AS IDENTITY</emphasis>,
254+
...,
255+
);
256+
</programlisting>
257+
or alternatively
258+
<programlisting>
259+
CREATE TABLE people (
260+
id bigint <emphasis>GENERATED BY DEFAULT IDENTITY</emphasis>,
261+
...,
262+
);
263+
</programlisting>
264+
See <xref linkend="sql-createtable"/> for more details.
265+
</para>
266+
267+
<para>
268+
If an <command>INSERT</command> command is executed on the table with the
269+
identity column and no value is explicitly specified for the identity
270+
column, then a value generated by the implicit sequence is inserted. For
271+
example, with the above definitions and assuming additional appropriate
272+
columns, writing
273+
<programlisting>
274+
INSERT INTO people (name, address) VALUE ('A', 'foo');
275+
INSERT INTO people (name, address) VALUE ('B', 'bar');
276+
</programlisting>
277+
would generate values for the <literal>id</literal> column starting at 1
278+
and result in the following table data:
279+
<screen>
280+
id | name | address
281+
----+------+---------
282+
1 | A | foo
283+
2 | B | bar
284+
</screen>
285+
Alternatively, the keyword <literal>DEFAULT</literal> can be specified in
286+
place of a value to explicitly request the sequence-generated value, like
287+
<programlisting>
288+
INSERT INTO people (id, name, address) VALUE (<emphasis>DEFAULT</emphasis>, 'C', 'baz');
289+
</programlisting>
290+
Similarly, the keyword <literal>DEFAULT</literal> can be used in
291+
<command>UPDATE</command> commands.
292+
</para>
293+
294+
<para>
295+
Thus, in many ways, an identity column behaves like a column with a default
296+
value.
297+
</para>
298+
299+
<para>
300+
The clauses <literal>ALWAYS</literal> and <literal>BY DEFAULT</literal> in
301+
the column definition determine how explicitly user-specified values are
302+
handled in <command>INSERT</command> and <command>UPDATE</command>
303+
commands. In an <command>INSERT</command> command, if
304+
<literal>ALWAYS</literal> is selected, a user-specified value is only
305+
accepted if the <command>INSERT</command> statement specifies
306+
<literal>OVERRIDING SYSTEM VALUE</literal>. If <literal>BY
307+
DEFAULT</literal> is selected, then the user-specified value takes
308+
precedence. Thus, using <literal>BY DEFAULT</literal> results in a
309+
behavior more similar to default values, where the default value can be
310+
overridden by an explicit value, whereas <literal>ALWAYS</literal> provides
311+
some more protection against accidentally inserting an explicit value.
312+
</para>
313+
314+
<para>
315+
The data type of an identity column must be one of the data types supported
316+
by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
317+
of the associated sequence may be specified when creating an identity
318+
column (see <xref linkend="sql-createtable"/>) or changed afterwards (see
319+
<xref linkend="sql-altertable"/>).
320+
</para>
321+
322+
<para>
323+
An identity column is automatically marked as <literal>NOT NULL</literal>.
324+
An identity column, however, does not guarantee uniqueness. (A sequence
325+
normally returns unique values, but a sequence could be reset, or values
326+
could be inserted manually into the identity column, as discussed above.)
327+
Uniqueness would need to be enforced using a <literal>PRIMARY KEY</literal>
328+
or <literal>UNIQUE</literal> constraint.
329+
</para>
330+
331+
<para>
332+
In table inheritance hierarchies, identity columns and their properties in
333+
a child table are independent of those in its parent tables. A child table
334+
does not inherit identity columns or their properties automatically from
335+
the parent. During <command>INSERT</command> or <command>UPDATE</command>,
336+
a column is treated as an identity column if that column is an identity
337+
column in the table named in the statement, and the corresponding identity
338+
properties are applied.
339+
</para>
340+
341+
<para>
342+
Identity columns are currently not supported for partitioned tables.
343+
</para>
344+
</sect1>
345+
236346
<sect1 id="ddl-generated-columns">
237347
<title>Generated Columns</title>
238348

0 commit comments

Comments
 (0)