rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Peter Eisentraut 2018-07-04 10:40:16 +02:00
parent fc057b2b8f
commit b46727e07a
1 changed files with 113 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
doc/src/sgml/ref/create_table.sgml
View File

@ -570,66 +570,124 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
possible to include data of the new table in scans of the original
table.
</para>
<para>
Default expressions for the copied column definitions will be copied
only if <literal>INCLUDING DEFAULTS</literal> is specified. The
default behavior is to exclude default expressions, 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>
Any identity specifications of copied column definitions will only be
copied if <literal>INCLUDING IDENTITY</literal> is specified. A new
sequence is created for each identity column of the new table, separate
from the sequences associated with the old table.
</para>
<para>
Not-null constraints are always copied to the new table.
<literal>CHECK</literal> constraints will be copied only if
<literal>INCLUDING CONSTRAINTS</literal> is specified.
No distinction is made between column constraints and table
constraints.
</para>
<para>
Extended statistics are copied to the new table if
<literal>INCLUDING STATISTICS</literal> is specified.
</para>
<para>
Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
and <literal>EXCLUDE</literal> constraints on the original table will be
created on the new table only if <literal>INCLUDING INDEXES</literal>
is specified. Names for the new indexes and constraints are
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>
<literal>STORAGE</literal> settings for the copied column definitions will be
copied only if <literal>INCLUDING STORAGE</literal> is specified. 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>
Comments for the copied columns, constraints, and indexes
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>
<literal>INCLUDING ALL</literal> is an abbreviated form of
<literal>INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS INCLUDING STORAGE</literal>.
</para>
<para>
Note that unlike <literal>INHERITS</literal>, columns and
<para>
Also unlike <literal>INHERITS</literal>, columns and
constraints copied by <literal>LIKE</literal> are not merged with similarly
named columns and constraints.
If the same name is specified explicitly or in another
<literal>LIKE</literal> clause, an error is signaled.
</para>
<para>
The optional <replaceable>like_option</replaceable> clauses specify
which additional properties of the original table to copy. Specifying
<literal>INCLUDING</literal> copies the property, specifying
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING CONSTRAINTS</literal></term>
<listitem>
<para>
<literal>CHECK</literal> constraints will be copied. No distinction
is made between column constraints and table constraints. Not-null
constraints are always copied to the new table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING DEFAULTS</literal></term>
<listitem>
<para>
Default expressions for the copied column definitions will be
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>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING IDENTITY</literal></term>
<listitem>
<para>
Any identity specifications of copied column definitions will be
copied. A new sequence is created for each identity column of the
new table, separate from the sequences associated with the old
table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING INDEXES</literal></term>
<listitem>
<para>
Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>,
and <literal>EXCLUDE</literal> constraints on the original table
will be created on the new table. Names for the new indexes and
constraints are 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>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING STATISTICS</literal></term>
<listitem>
<para>
Extended statistics are copied to the new table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING STORAGE</literal></term>
<listitem>
<para>
<literal>STORAGE</literal> settings for the copied column
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>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INCLUDING ALL</literal></term>
<listitem>
<para>
<literal>INCLUDING ALL</literal> is an abbreviated form selecting
all the available individual options. (It could be useful to write
individual <literal>EXCLUDING</literal> clauses after
<literal>INCLUDING ALL</literal> to select all but some specific
options.)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The <literal>LIKE</literal> clause can also be used to copy column
definitions from views, foreign tables, or composite types.