Provide adequate documentation of the "table_name *" notation.

Somewhere along the line, somebody decided to remove all trace of this
notation from the documentation text.  It was still in the command syntax
synopses, or at least some of them, but with no indication what it meant.
This will not do, as evidenced by the confusion apparent in bug #7543;
even if the notation is now unnecessary, people will find it in legacy
SQL code and need to know what it does.

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 9591f7cd41fef386888d51328c6d371597e5c632..7ac7b983855138f055d5bf503d699a7686129bd4 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4648,11 +4648,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 included 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 98233866300c6e3c50d1d16e310f2c842d7bd03a..37f0cbfddb6aca7478816b18857bdfd73cd8e77b 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1995,6 +1995,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 &gt; 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
@@ -2182,18 +2199,6 @@ VALUES ('New York', NULL, NULL, 'NY');
    inheritance is useful for your problem.
   </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 b5b5542d51aedf5f33db356afcef085b6919a420..027768baf41ea8b7df8aa93826aeac49a459acab 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -139,6 +139,16 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
     &mdash; 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 d6bf184d649e54ee867136941a456b8e86355415..2a1cd0027d9b68b012cbf468add0946485702f2a 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -433,15 +433,12 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <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 all
-        its descendant tables (if any) are updated. <literal>*</> can be
-        appended to the table name to indicate that descendant tables are
-        to be altered, but in the current version, this is the default
-        behavior.  (In releases before 7.1, <literal>ONLY</> was the
-        default behavior.  The default can be altered by changing the
-        configuration parameter <xref linkend="guc-sql-inheritance">.)
+        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>

diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index 6e3d9ff2c1fad9bb1790b01a504606dd86fb8dcc..81e77fdf39a51ade6452c5c53d066d79cfd35b17 100644 (file)
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -20,7 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
+DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
     [ USING <replaceable class="PARAMETER">usinglist</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> ] [, ...] ]
@@ -45,13 +45,6 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
     </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
@@ -82,21 +75,17 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
   <title>Parameters</title>
 
   <variablelist>
-   <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</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/select.sgml b/doc/src/sgml/ref/select.sgml
index b000dbb1f5b3cf3c56997c2fbe9b25a93b08045a..b3b6cfb2ec5e8053c39841d746f6374892aa57aa 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -184,16 +184,12 @@ where <replaceable class="parameter">from_item</replaceable> can be one of:
       <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
-        all its descendant tables (if any) are scanned.  <literal>*</>
-        can be appended to the table name to indicate that descendant
-        tables are to be scanned, but in the current version, this is
-        the default behavior.  (In releases before 7.1,
-        <literal>ONLY</> was the default behavior.)  The default
-        behavior can be modified by changing the <xref
-        linkend="guc-sql-inheritance"> configuration option.
+        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>

diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index ce05150073a6ccb284bc3fdc273aca8f2ea6d386..8f39a7d0c166209cb77f4f5004bf51d1e837fc0e 100644 (file)
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -20,7 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
+UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
     SET { <replaceable class="PARAMETER">column</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } |
           ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) = ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
     [ FROM <replaceable class="PARAMETER">fromlist</replaceable> ]
@@ -39,13 +39,6 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
    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
@@ -82,6 +75,11 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
     <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>