From 46b773d4fe0f0c880a1073cb5366efa02efa8ef8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 28 Jul 2016 13:26:58 -0400 Subject: [PATCH] Improve documentation about CREATE TABLE ... LIKE. The docs failed to explain that LIKE INCLUDING INDEXES would not preserve the names of indexes and associated constraints. Also, it wasn't mentioned that EXCLUDE constraints would be copied by this option. The latter oversight seems enough of a documentation bug to justify back-patching. In passing, do some minor copy-editing in the same area, and add an entry for LIKE under "Compatibility", since it's not exactly a faithful implementation of the standard's feature. Discussion: <20160728151154.AABE64016B@smtp.hushmail.com> --- doc/src/sgml/ref/create_table.sgml | 52 +++++++++++++++++++++--------- src/backend/parser/parse_utilcmd.c | 4 ++- 2 files changed, 39 insertions(+), 17 deletions(-) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 06e6392f737..bf2ad64d66e 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -329,26 +329,33 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI table. - Default expressions for the copied column definitions will only be - copied if INCLUDING DEFAULTS is specified. - Defaults that call database-modification functions, like - nextval, create a linkage between the original and - new tables. The + 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. Not-null constraints are always copied to the new table. CHECK constraints will be copied only if INCLUDING CONSTRAINTS is specified. - Indexes, PRIMARY KEY, and UNIQUE constraints - on the original table will be created on the new table only if the - INCLUDING INDEXES clause is specified. No distinction is made between column constraints and table constraints. - STORAGE settings for the copied column definitions will only - be copied if INCLUDING STORAGE is specified. The + + 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 @@ -356,24 +363,26 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI Comments for the copied columns, constraints, and indexes - will only be copied if INCLUDING COMMENTS + 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 ALL is an abbreviated form of INCLUDING DEFAULTS INCLUDING CONSTRAINTS INCLUDING INDEXES INCLUDING STORAGE INCLUDING COMMENTS. - Note also that unlike INHERITS, columns and + Note that 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 LIKE clause can also be used to copy columns from - views, foreign tables, or composite types. Inapplicable options (e.g., INCLUDING - INDEXES from a view) are ignored. + The LIKE clause can also be used to copy column + definitions from views, foreign tables, or composite types. + Inapplicable options (e.g., INCLUDING INDEXES from + a view) are ignored. @@ -1499,6 +1508,17 @@ CREATE TABLE employees OF employee_type ( + + <literal>LIKE</> Clause + + + While a LIKE clause exists in the SQL standard, many of the + options that PostgreSQL accepts for it are not + in the standard, and some of the standard's options are not implemented + by PostgreSQL. + + + <literal>WITH</> Clause diff --git a/src/backend/parser/parse_utilcmd.c b/src/backend/parser/parse_utilcmd.c index 6313087174d..e98fad051e4 100644 --- a/src/backend/parser/parse_utilcmd.c +++ b/src/backend/parser/parse_utilcmd.c @@ -1143,7 +1143,9 @@ generateClonedIndexStmt(CreateStmtContext *cxt, Relation source_idx, /* * We don't try to preserve the name of the source index; instead, just - * let DefineIndex() choose a reasonable name. + * let DefineIndex() choose a reasonable name. (If we tried to preserve + * the name, we'd get duplicate-relation-name failures unless the source + * table was in a different schema.) */ index->idxname = NULL;