Skip to content

P
Postgres FD Implementation
Commit b46727e0 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

doc: Reorganize CREATE TABLE / LIKE option documentation 

This section once started out small but has now grown quite a bit and
needs a bit of structure.

Rewrite as list, add documentation of EXCLUDING, and improve the
documentation of INCLUDING ALL instead of just listing all the options
again.

per report from Yugo Nagata that EXCLUDING was not documented, that part
reviewed by Daniel Gustafsson, most of the rewrite was by me
parent fc057b2b
Show whitespace changes
Inline Side-by-side
Showing with 113 additions and 55 deletions
doc/src/sgml/ref/create_table.sgml
View file @ b46727e0
...@@ -571,65 +571,123 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM ...@@ -571,65 +571,123 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
table. table.
</para> </para>
<para> <para>
Default expressions for the copied column definitions will be copied Also unlike <literal>INHERITS</literal>, columns and
only if <literal>INCLUDING DEFAULTS</literal> is specified. The constraints copied by <literal>LIKE</literal> are not merged with similarly
default behavior is to exclude default expressions, resulting in the named columns and constraints.
copied columns in the new table having null defaults. If the same name is specified explicitly or in another
Note that copying defaults that call database-modification functions, <literal>LIKE</literal> clause, an error is signaled.
such as <function>nextval</function>, may create a functional linkage between
the original and new tables.
</para> </para>
<para> <para>
Any identity specifications of copied column definitions will only be The optional <replaceable>like_option</replaceable> clauses specify
copied if <literal>INCLUDING IDENTITY</literal> is specified. A new which additional properties of the original table to copy. Specifying
sequence is created for each identity column of the new table, separate <literal>INCLUDING</literal> copies the property, specifying
from the sequences associated with the old table. <literal>EXCLUDING</literal> omits the property.
<literal>EXCLUDING</literal> is the default. If multiple specifications
are made for the same kind of object, the last one is used. The
available options are:
<variablelist>
<varlistentry>
<term><literal>INCLUDING COMMENTS</literal></term>
<listitem>
<para>
Comments for the copied columns, constraints, and indexes will be
copied. The default behavior is to exclude comments, resulting in
the copied columns and constraints in the new table having no
comments.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING CONSTRAINTS</literal></term>
<listitem>
<para> <para>
Not-null constraints are always copied to the new table. <literal>CHECK</literal> constraints will be copied. No distinction
<literal>CHECK</literal> constraints will be copied only if is made between column constraints and table constraints. Not-null
<literal>INCLUDING CONSTRAINTS</literal> is specified. constraints are always copied to the new table.
No distinction is made between column constraints and table
constraints.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING DEFAULTS</literal></term>
<listitem>
<para> <para>
Extended statistics are copied to the new table if Default expressions for the copied column definitions will be
<literal>INCLUDING STATISTICS</literal> is specified. copied. Otherwise, default expressions are not copied, resulting in
the copied columns in the new table having null defaults. Note that
copying defaults that call database-modification functions, such as
<function>nextval</function>, may create a functional linkage
between the original and new tables.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING IDENTITY</literal></term>
<listitem>
<para> <para>
Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>, Any identity specifications of copied column definitions will be
and <literal>EXCLUDE</literal> constraints on the original table will be copied. A new sequence is created for each identity column of the
created on the new table only if <literal>INCLUDING INDEXES</literal> new table, separate from the sequences associated with the old
is specified. Names for the new indexes and constraints are table.
chosen according to the default rules, regardless of how the originals
were named. (This behavior avoids possible duplicate-name failures for
the new indexes.)
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING INDEXES</literal></term>
<listitem>
<para> <para>
<literal>STORAGE</literal> settings for the copied column definitions will be Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
copied only if <literal>INCLUDING STORAGE</literal> is specified. The and <literal>EXCLUDE</literal> constraints on the original table
default behavior is to exclude <literal>STORAGE</literal> settings, resulting will be created on the new table. Names for the new indexes and
in the copied columns in the new table having type-specific default constraints are chosen according to the default rules, regardless of
settings. For more on <literal>STORAGE</literal> settings, see how the originals were named. (This behavior avoids possible
<xref linkend="storage-toast"/>. duplicate-name failures for the new indexes.)
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING STATISTICS</literal></term>
<listitem>
<para> <para>
Comments for the copied columns, constraints, and indexes Extended statistics are copied to the new table.
will be copied only if <literal>INCLUDING COMMENTS</literal>
is specified. The default behavior is to exclude comments, resulting in
the copied columns and constraints in the new table having no comments.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING STORAGE</literal></term>
<listitem>
<para> <para>
<literal>INCLUDING ALL</literal> is an abbreviated form of <literal>STORAGE</literal> settings for the copied column
<literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS INCLUDING STORAGE</literal>. definitions will be copied. The default behavior is to exclude
<literal>STORAGE</literal> settings, resulting in the copied columns
in the new table having type-specific default settings. For more on
<literal>STORAGE</literal> settings, see <xref
linkend="storage-toast"/>.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING ALL</literal></term>
<listitem>
<para> <para>
Note that unlike <literal>INHERITS</literal>, columns and <literal>INCLUDING ALL</literal> is an abbreviated form selecting
constraints copied by <literal>LIKE</literal> are not merged with similarly all the available individual options. (It could be useful to write
named columns and constraints. individual <literal>EXCLUDING</literal> clauses after
If the same name is specified explicitly or in another <literal>INCLUDING ALL</literal> to select all but some specific
<literal>LIKE</literal> clause, an error is signaled. options.)
</para> </para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para> <para>
The <literal>LIKE</literal> clause can also be used to copy column The <literal>LIKE</literal> clause can also be used to copy column
definitions from views, foreign tables, or composite types. definitions from views, foreign tables, or composite types.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment