diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 29e5d11a518b721d8c7bdaa87b43339c2251051c..5891903c8f686c577da602eb62703c5f1d40de3a 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5795,11 +5795,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
<indexterm><primary>inheritance</></>
<listitem>
<para>
- This controls the inheritance semantics. If turned <literal>off</>,
- subtables are not accessed by various commands by default; basically
- an implied <literal>ONLY</literal> key word. This was added for
- compatibility with releases prior to 7.1. See
- <xref linkend="ddl-inherit"> for more information.
+ This setting controls whether undecorated table references are
+ considered to include inheritance child tables. The default is
+ <literal>on</>, which means child tables are included (thus,
+ a <literal>*</> suffix is assumed by default). If turned
+ <literal>off</>, child tables are not included (thus, an
+ <literal>ONLY</literal> prefix is assumed). The SQL standard
+ requires child tables to be included, so the <literal>off</> setting
+ is not spec-compliant, but it is provided for compatibility with
+ <productname>PostgreSQL</> releases prior to 7.1.
+ See <xref linkend="ddl-inherit"> for more information.
+ </para>
+
+ <para>
+ Turning <varname>sql_inheritance</> off is deprecated, because that
+ behavior has been found to be error-prone as well as contrary to SQL
+ standard. Discussions of inheritance behavior elsewhere in this
+ manual generally assume that it is <literal>on</>.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index e52dff2dd52bd2f16be34214ef7481fdf2630416..f0b60b55009e00c083c53b3ee968f5120d4281f4 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2062,6 +2062,23 @@ SELECT name, altitude
<literal>ONLY</literal> keyword.
</para>
+ <para>
+ You can also write the table name with a trailing <literal>*</>
+ to explicitly specify that descendant tables are included:
+
+<programlisting>
+SELECT name, altitude
+ FROM cities*
+ WHERE altitude > 500;
+</programlisting>
+
+ Writing <literal>*</> is not necessary, since this behavior is
+ the default (unless you have changed the setting of the
+ <xref linkend="guc-sql-inheritance"> configuration option).
+ However writing <literal>*</> might be useful to emphasize that
+ additional tables will be searched.
+ </para>
+
<para>
In some cases you might wish to know which table a particular row
originated from. There is a system column called
@@ -2209,15 +2226,15 @@ VALUES ('New York', NULL, NULL, 'NY');
data modification, or schema modification
(e.g., <literal>SELECT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>,
most variants of <literal>ALTER TABLE</literal>, but
- not <literal>INSERT</literal> and <literal>ALTER TABLE ...
+ not <literal>INSERT</literal> or <literal>ALTER TABLE ...
RENAME</literal>) typically default to including child tables and
support the <literal>ONLY</literal> notation to exclude them.
Commands that do database maintenance and tuning
(e.g., <literal>REINDEX</literal>, <literal>VACUUM</literal>)
- typically only work on individual, physical tables and do no
+ typically only work on individual, physical tables and do not
support recursing over inheritance hierarchies. The respective
- behavior of each individual command is documented in the reference
- part (<xref linkend="sql-commands">).
+ behavior of each individual command is documented in its reference
+ page (<xref linkend="sql-commands">).
</para>
<para>
@@ -2267,18 +2284,6 @@ VALUES ('New York', NULL, NULL, 'NY');
inheritance is useful for your application.
</para>
- <note>
- <title>Deprecated</title>
- <para>
- In releases of <productname>PostgreSQL</productname> prior to 7.1, the
- default behavior was not to include child tables in queries. This was
- found to be error prone and also in violation of the SQL
- standard. You can get the pre-7.1 behavior by turning off the
- <xref linkend="guc-sql-inheritance"> configuration
- option.
- </para>
- </note>
-
</sect2>
</sect1>
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 8fc12c5ab88ba683e069ac1b61fc14e2df9409e1..850e8921d9eb72d020c3b80f90c00f7056efa99b 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -140,6 +140,16 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
— any columns added in subtables are ignored.
</para>
+ <para>
+ Instead of writing <literal>ONLY</> before the table name, you can write
+ <literal>*</> after the table name to explicitly specify that descendant
+ tables are included. Writing <literal>*</> is not necessary since that
+ behavior is the default (unless you have changed the setting of the <xref
+ linkend="guc-sql-inheritance"> configuration option). However writing
+ <literal>*</> might be useful to emphasize that additional tables will be
+ searched.
+ </para>
+
<sect3 id="queries-join">
<title>Joined Tables</title>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index b7648142eea408a9990c2188b6a869f861d1168b..356419e2d08d11ade4fb9fbc3ad0e41966523646 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -625,10 +625,12 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- The name (possibly schema-qualified) of an existing table to
- alter. If <literal>ONLY</> is specified, only that table is
- altered. If <literal>ONLY</> is not specified, the table and any
- descendant tables are altered.
+ The name (optionally schema-qualified) of an existing table to
+ alter. If <literal>ONLY</> is specified before the table name, only
+ that table is altered. If <literal>ONLY</> is not specified, the table
+ and all its descendant tables (if any) are altered. Optionally,
+ <literal>*</> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
</para>
</listitem>
</varlistentry>
@@ -1026,7 +1028,7 @@ ALTER TABLE distributors DROP CONSTRAINT zipchk;
</para>
<para>
- To remove a check constraint from a table only:
+ To remove a check constraint from one table only:
<programlisting>
ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
</programlisting>
diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index 2a9841d706cb884259722e266d2855128a9781b5..5d2ad3fde56c7f7c37123add2c24e200024de996 100644
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
-DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
+DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
[ USING <replaceable class="PARAMETER">using_list</replaceable> ]
[ WHERE <replaceable class="PARAMETER">condition</replaceable> | WHERE CURRENT OF <replaceable class="PARAMETER">cursor_name</replaceable> ]
[ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
@@ -47,13 +47,6 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [
</para>
</tip>
- <para>
- By default, <command>DELETE</command> will delete rows in the
- specified table and all its child tables. If you wish to delete only
- from the specific table mentioned, you must use the
- <literal>ONLY</literal> clause.
- </para>
-
<para>
There are two ways to delete rows in a table using information
contained in other tables in the database: using sub-selects, or
@@ -96,21 +89,17 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>ONLY</></term>
- <listitem>
- <para>
- If specified, delete rows from the named table only. When not
- specified, any tables inheriting from the named table are also processed.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><replaceable class="parameter">table_name</replaceable></term>
<listitem>
<para>
- The name (optionally schema-qualified) of an existing table.
+ The name (optionally schema-qualified) of the table to delete rows
+ from. If <literal>ONLY</> is specified before the table name,
+ matching rows are deleted from the named table only. If
+ <literal>ONLY</> is not specified, matching rows are also deleted
+ from any tables inheriting from the named table. Optionally,
+ <literal>*</> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml
index 53014ed34f5edfde8ec87942c4a5dfa5c1042a68..05acbc4f60691be6d576d117be36af89a927b913 100644
--- a/doc/src/sgml/ref/lock.sgml
+++ b/doc/src/sgml/ref/lock.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ IN <replaceable class="PARAMETER">lockmode</replaceable> MODE ] [ NOWAIT ]
+LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ] [, ...] [ IN <replaceable class="PARAMETER">lockmode</replaceable> MODE ] [ NOWAIT ]
<phrase>where <replaceable class="PARAMETER">lockmode</replaceable> is one of:</phrase>
@@ -111,9 +111,11 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ...
<listitem>
<para>
The name (optionally schema-qualified) of an existing table to
- lock. If <literal>ONLY</> is specified, only that table is
- locked. If <literal>ONLY</> is not specified, the table and all
- its descendant tables (if any) are locked.
+ lock. If <literal>ONLY</> is specified before the table name, only that
+ table is locked. If <literal>ONLY</> is not specified, the table and all
+ its descendant tables (if any) are locked. Optionally, <literal>*</>
+ can be specified after the table name to explicitly indicate that
+ descendant tables are included.
</para>
<para>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 7e989242587cbb897cf22ff05a565e77c0246957..ad4f7a3393659349e561fd1377b6a69c0bea3d72 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -298,10 +298,12 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
<term><replaceable class="parameter">table_name</replaceable></term>
<listitem>
<para>
- The name (optionally schema-qualified) of an existing table or
- view. If <literal>ONLY</> is specified, only that table is
- scanned. If <literal>ONLY</> is not specified, the table and
- any descendant tables are scanned.
+ The name (optionally schema-qualified) of an existing table or view.
+ If <literal>ONLY</> is specified before the table name, only that
+ table is scanned. If <literal>ONLY</> is not specified, the table
+ and all its descendant tables (if any) are scanned. Optionally,
+ <literal>*</> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
</para>
</listitem>
</varlistentry>
@@ -1599,15 +1601,24 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
</refsect2>
<refsect2>
- <title><literal>ONLY</literal> and Parentheses</title>
+ <title><literal>ONLY</literal> and Inheritance</title>
<para>
- The SQL standard requires parentheses around the table name
- after <literal>ONLY</literal>, as in <literal>SELECT * FROM ONLY
- (tab1), ONLY (tab2) WHERE ...</literal>. PostgreSQL supports that
- as well, but the parentheses are optional. (This point applies
- equally to all SQL commands supporting the <literal>ONLY</literal>
- option.)
+ The SQL standard requires parentheses around the table name when
+ writing <literal>ONLY</literal>, for example <literal>SELECT * FROM ONLY
+ (tab1), ONLY (tab2) WHERE ...</literal>. <productname>PostgreSQL</>
+ considers these parentheses to be optional.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</> allows a trailing <literal>*</> to be written to
+ explicitly specify the non-<literal>ONLY</literal> behavior of including
+ child tables. The standard does not allow this.
+ </para>
+
+ <para>
+ (These points apply equally to all SQL commands supporting the
+ <literal>ONLY</literal> option.)
</para>
</refsect2>
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 2fe47ca81626dd41cee373bb2b004cd122657886..7b9c2f30128fbb3283b1e8fc0467134a574051c0 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ... ]
+TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ] [, ... ]
[ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
@@ -47,10 +47,12 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [,
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- The name (optionally schema-qualified) of a table to be
- truncated. If <literal>ONLY</> is specified, only that table is
- truncated. If <literal>ONLY</> is not specified, the table and
- all its descendant tables (if any) are truncated.
+ The name (optionally schema-qualified) of a table to truncate.
+ If <literal>ONLY</> is specified before the table name, only that table
+ is truncated. If <literal>ONLY</> is not specified, the table and all
+ its descendant tables (if any) are truncated. Optionally, <literal>*</>
+ can be specified after the table name to explicitly indicate that
+ descendant tables are included.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index c575374dd0d3c0b370da5ec73d4a2a1825b11732..90b92085cd2272946a0d1b99d82f16eff8afc01d 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
-UPDATE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
+UPDATE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
SET { <replaceable class="PARAMETER">column_name</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } |
( <replaceable class="PARAMETER">column_name</replaceable> [, ...] ) = ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
[ FROM <replaceable class="PARAMETER">from_list</replaceable> ]
@@ -41,13 +41,6 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [ AS ]
columns not explicitly modified retain their previous values.
</para>
- <para>
- By default, <command>UPDATE</command> will update rows in the
- specified table and all its subtables. If you wish to only update
- the specific table mentioned, you must use the <literal>ONLY</>
- clause.
- </para>
-
<para>
There are two ways to modify a table using information contained in
other tables in the database: using sub-selects, or specifying
@@ -97,6 +90,11 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ [ AS ]
<listitem>
<para>
The name (optionally schema-qualified) of the table to update.
+ If <literal>ONLY</> is specified before the table name, matching rows
+ are updated in the named table only. If <literal>ONLY</> is not
+ specified, matching rows are also updated in any tables inheriting from
+ the named table. Optionally, <literal>*</> can be specified after the
+ table name to explicitly indicate that descendant tables are included.
</para>
</listitem>
</varlistentry>