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>

diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 0a6e0fc87a819467a97dede78aefa682b02e13ca..fc92d6bc588f118d2483b15898a200860a33e39e 100644 (file)
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -321,26 +321,33 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
       table.
      </para>
      <para>
-      Default expressions for the copied column definitions will only be
-      copied if <literal>INCLUDING DEFAULTS</literal> is specified.  The
+      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</>, may create a functional linkage between
+      the original and new tables.
      </para>
      <para>
       Not-null constraints are always copied to the new table.
-      <literal>CHECK</literal> constraints will only be copied if
-      <literal>INCLUDING CONSTRAINTS</literal> is specified; other types of
-      constraints will never be copied. Also, no distinction is made between
-      column constraints and table constraints &mdash; when constraints are
-      requested, all check constraints are copied.
+      <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>
-      Any indexes on the original table will not be created on the new
-      table, unless the <literal>INCLUDING INDEXES</literal> clause is
-      specified.
+      Indexes, <literal>PRIMARY KEY</>, <literal>UNIQUE</>,
+      and <literal>EXCLUDE</> 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</> settings for the copied column definitions will only
-      be copied if <literal>INCLUDING STORAGE</literal> is specified.  The
+     <para>
+      <literal>STORAGE</> 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</> settings, resulting
       in the copied columns in the new table having type-specific default
       settings.  For more on <literal>STORAGE</> settings, see
@@ -348,19 +355,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
      </para>
      <para>
       Comments for the copied columns, constraints, and indexes
-      will only be copied if <literal>INCLUDING COMMENTS</literal>
+      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
+     <para>
+      <literal>INCLUDING ALL</literal> is an abbreviated form of
       <literal>INCLUDING DEFAULTS INCLUDING CONSTRAINTS INCLUDING INDEXES INCLUDING STORAGE INCLUDING COMMENTS</literal>.
      </para>
      <para>
-      Note also that unlike <literal>INHERITS</literal>, columns and
+      Note that unlike <literal>INHERITS</literal>, columns and
       constraints copied by <literal>LIKE</> 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 signalled.
+      <literal>LIKE</literal> clause, an error is signaled.
      </para>
     </listitem>
    </varlistentry>
@@ -1381,6 +1389,17 @@ CREATE TABLE employees OF employee_type (
    </para>
   </refsect2>
 
+  <refsect2>
+   <title><literal>LIKE</> Clause</title>
+
+   <para>
+    While a <literal>LIKE</> clause exists in the SQL standard, many of the
+    options that <productname>PostgreSQL</productname> accepts for it are not
+    in the standard, and some of the standard's options are not implemented
+    by <productname>PostgreSQL</productname>.
+   </para>
+  </refsect2>
+
   <refsect2>
    <title><literal>WITH</> Clause</title>
 

diff --git a/src/backend/parser/parse_utilcmd.c b/src/backend/parser/parse_utilcmd.c
index eb4e4212fc90cee8908b69ebbcc65f26eb559ed9..0ba59927eed4dc31baabcc545e85af4dee7111bc 100644 (file)
--- a/src/backend/parser/parse_utilcmd.c
+++ b/src/backend/parser/parse_utilcmd.c
@@ -1010,7 +1010,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;