Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 46b773d

Browse files
committed
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>
1 parent d9e7495 commit 46b773d

File tree

2 files changed

+39
-17
lines changed

2 files changed

+39
-17
lines changed

doc/src/sgml/ref/create_table.sgml

+36-16
Original file line numberDiff line numberDiff line change
@@ -329,51 +329,60 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
329329
table.
330330
</para>
331331
<para>
332-
Default expressions for the copied column definitions will only be
333-
copied if <literal>INCLUDING DEFAULTS</literal> is specified.
334-
Defaults that call database-modification functions, like
335-
<function>nextval</>, create a linkage between the original and
336-
new tables. The
332+
Default expressions for the copied column definitions will be copied
333+
only if <literal>INCLUDING DEFAULTS</literal> is specified. The
337334
default behavior is to exclude default expressions, resulting in the
338335
copied columns in the new table having null defaults.
336+
Note that copying defaults that call database-modification functions,
337+
such as <function>nextval</>, may create a functional linkage between
338+
the original and new tables.
339339
</para>
340340
<para>
341341
Not-null constraints are always copied to the new table.
342342
<literal>CHECK</literal> constraints will be copied only if
343343
<literal>INCLUDING CONSTRAINTS</literal> is specified.
344-
Indexes, <literal>PRIMARY KEY</>, and <literal>UNIQUE</> constraints
345-
on the original table will be created on the new table only if the
346-
<literal>INCLUDING INDEXES</literal> clause is specified.
347344
No distinction is made between column constraints and table
348345
constraints.
349346
</para>
350-
<para><literal>STORAGE</> settings for the copied column definitions will only
351-
be copied if <literal>INCLUDING STORAGE</literal> is specified. The
347+
<para>
348+
Indexes, <literal>PRIMARY KEY</>, <literal>UNIQUE</>,
349+
and <literal>EXCLUDE</> constraints on the original table will be
350+
created on the new table only if <literal>INCLUDING INDEXES</literal>
351+
is specified. Names for the new indexes and constraints are
352+
chosen according to the default rules, regardless of how the originals
353+
were named. (This behavior avoids possible duplicate-name failures for
354+
the new indexes.)
355+
</para>
356+
<para>
357+
<literal>STORAGE</> settings for the copied column definitions will be
358+
copied only if <literal>INCLUDING STORAGE</literal> is specified. The
352359
default behavior is to exclude <literal>STORAGE</> settings, resulting
353360
in the copied columns in the new table having type-specific default
354361
settings. For more on <literal>STORAGE</> settings, see
355362
<xref linkend="storage-toast">.
356363
</para>
357364
<para>
358365
Comments for the copied columns, constraints, and indexes
359-
will only be copied if <literal>INCLUDING COMMENTS</literal>
366+
will be copied only if <literal>INCLUDING COMMENTS</literal>
360367
is specified. The default behavior is to exclude comments, resulting in
361368
the copied columns and constraints in the new table having no comments.
362369
</para>
363-
<para><literal>INCLUDING ALL</literal> is an abbreviated form of
370+
<para>
371+
<literal>INCLUDING ALL</literal> is an abbreviated form of
364372
<literal>INCLUDING DEFAULTS INCLUDING CONSTRAINTS INCLUDING INDEXES INCLUDING STORAGE INCLUDING COMMENTS</literal>.
365373
</para>
366374
<para>
367-
Note also that unlike <literal>INHERITS</literal>, columns and
375+
Note that unlike <literal>INHERITS</literal>, columns and
368376
constraints copied by <literal>LIKE</> are not merged with similarly
369377
named columns and constraints.
370378
If the same name is specified explicitly or in another
371379
<literal>LIKE</literal> clause, an error is signaled.
372380
</para>
373381
<para>
374-
The <literal>LIKE</literal> clause can also be used to copy columns from
375-
views, foreign tables, or composite types. Inapplicable options (e.g., <literal>INCLUDING
376-
INDEXES</literal> from a view) are ignored.
382+
The <literal>LIKE</literal> clause can also be used to copy column
383+
definitions from views, foreign tables, or composite types.
384+
Inapplicable options (e.g., <literal>INCLUDING INDEXES</literal> from
385+
a view) are ignored.
377386
</para>
378387
</listitem>
379388
</varlistentry>
@@ -1499,6 +1508,17 @@ CREATE TABLE employees OF employee_type (
14991508
</para>
15001509
</refsect2>
15011510

1511+
<refsect2>
1512+
<title><literal>LIKE</> Clause</title>
1513+
1514+
<para>
1515+
While a <literal>LIKE</> clause exists in the SQL standard, many of the
1516+
options that <productname>PostgreSQL</productname> accepts for it are not
1517+
in the standard, and some of the standard's options are not implemented
1518+
by <productname>PostgreSQL</productname>.
1519+
</para>
1520+
</refsect2>
1521+
15021522
<refsect2>
15031523
<title><literal>WITH</> Clause</title>
15041524

src/backend/parser/parse_utilcmd.c

+3-1
Original file line numberDiff line numberDiff line change
@@ -1143,7 +1143,9 @@ generateClonedIndexStmt(CreateStmtContext *cxt, Relation source_idx,
11431143

11441144
/*
11451145
* We don't try to preserve the name of the source index; instead, just
1146-
* let DefineIndex() choose a reasonable name.
1146+
* let DefineIndex() choose a reasonable name. (If we tried to preserve
1147+
* the name, we'd get duplicate-relation-name failures unless the source
1148+
* table was in a different schema.)
11471149
*/
11481150
index->idxname = NULL;
11491151

0 commit comments

Comments
 (0)