From b46727e07a9f4b8e0c8de1f10bfd4986b02c154c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 4 Jul 2018 10:40:16 +0200 Subject: [PATCH] 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 --- doc/src/sgml/ref/create_table.sgml | 168 +++++++++++++++++++---------- 1 file changed, 113 insertions(+), 55 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 2a1eac9592..b449520940 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -570,66 +570,124 @@ WITH ( MODULUS numeric_literal, REM possible to include data of the new table in scans of the original table. - - Default expressions for the copied column definitions will be copied - only if INCLUDING DEFAULTS 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 nextval, may create a functional linkage between - the original and new tables. - - - Any identity specifications of copied column definitions will only be - copied if INCLUDING IDENTITY is specified. A new - sequence is created for each identity column of the new table, separate - from the sequences associated with the old table. - - - Not-null constraints are always copied to the new table. - CHECK constraints will be copied only if - INCLUDING CONSTRAINTS is specified. - No distinction is made between column constraints and table - constraints. - - - Extended statistics are copied to the new table if - INCLUDING STATISTICS is specified. - - - Indexes, PRIMARY KEY, UNIQUE, - and EXCLUDE constraints on the original table will be - created on the new table only if INCLUDING INDEXES - 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.) - - - STORAGE settings for the copied column definitions will be - copied only if INCLUDING STORAGE is specified. The - default behavior is to exclude STORAGE settings, resulting - in the copied columns in the new table having type-specific default - settings. For more on STORAGE settings, see - . - - - Comments for the copied columns, constraints, and indexes - will be copied only if INCLUDING COMMENTS - is specified. The default behavior is to exclude comments, resulting in - the copied columns and constraints in the new table having no comments. - - - INCLUDING ALL is an abbreviated form of - INCLUDING COMMENTS INCLUDING CONSTRAINTS INCLUDING DEFAULTS INCLUDING IDENTITY INCLUDING INDEXES INCLUDING STATISTICS INCLUDING STORAGE. - - - Note that unlike INHERITS, columns and + + Also unlike INHERITS, columns and constraints copied by LIKE are not merged with similarly named columns and constraints. If the same name is specified explicitly or in another LIKE clause, an error is signaled. + + The optional like_option clauses specify + which additional properties of the original table to copy. Specifying + INCLUDING copies the property, specifying + EXCLUDING omits the property. + EXCLUDING is the default. If multiple specifications + are made for the same kind of object, the last one is used. The + available options are: + + + + INCLUDING COMMENTS + + + 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. + + + + + + INCLUDING CONSTRAINTS + + + CHECK constraints will be copied. No distinction + is made between column constraints and table constraints. Not-null + constraints are always copied to the new table. + + + + + + INCLUDING DEFAULTS + + + 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 + nextval, may create a functional linkage + between the original and new tables. + + + + + + INCLUDING IDENTITY + + + 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. + + + + + + INCLUDING INDEXES + + + Indexes, PRIMARY KEY, UNIQUE, + and EXCLUDE 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.) + + + + + + INCLUDING STATISTICS + + + Extended statistics are copied to the new table. + + + + + + INCLUDING STORAGE + + + STORAGE settings for the copied column + definitions will be copied. The default behavior is to exclude + STORAGE settings, resulting in the copied columns + in the new table having type-specific default settings. For more on + STORAGE settings, see . + + + + + + INCLUDING ALL + + + INCLUDING ALL is an abbreviated form selecting + all the available individual options. (It could be useful to write + individual EXCLUDING clauses after + INCLUDING ALL to select all but some specific + options.) + + + + + + The LIKE clause can also be used to copy column definitions from views, foreign tables, or composite types. -- 2.40.0