@@ -233,6 +233,116 @@ CREATE TABLE products (
233
233
</para>
234
234
</sect1>
235
235
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
+
236
346
<sect1 id="ddl-generated-columns">
237
347
<title>Generated Columns</title>
238
348
0 commit comments