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 b8eaac39eaf7c587d8972571a32d9134248c2069..8ec8a6f663594baf9159c42101f93226f214ed1e 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5236,11 +5236,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       inheritance
       
        
-        This controls the inheritance semantics.  If turned off,
-        subtables are not accessed by various commands by default; basically
-        an implied ONLY key word.  This was added for 
-        compatibility with releases prior to 7.1.  See
-         for more information.
+        This setting controls whether undecorated table references are
+        considered to include inheritance child tables.  The default is
+        on, which means child tables are included (thus,
+        a * suffix is assumed by default).  If turned
+        off, child tables are not included (thus, an
+        ONLY prefix is assumed).  The SQL standard
+        requires child tables to be included, so the off setting
+        is not spec-compliant, but it is provided for compatibility with
+        PostgreSQL releases prior to 7.1.
+        See  for more information.
+       
+
+       
+        Turning 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 on.
        
       
      

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 038f92e1d525bb4e67afee8e49f390133619636d..d0fcdc74e0b145d96d858bc69a6df873fb861ffb 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2050,6 +2050,23 @@ SELECT name, altitude
    ONLY keyword.
   
 
+  
+   You can also write the table name with a trailing *
+   to explicitly specify that descendant tables are included:
+
+
+SELECT name, altitude
+    FROM cities*
+    WHERE altitude > 500;
+
+
+   Writing * is not necessary, since this behavior is
+   the default (unless you have changed the setting of the
+    configuration option).
+   However writing * might be useful to emphasize that
+   additional tables will be searched.
+  
+
   
    In some cases you might wish to know which table a particular row
    originated from. There is a system column called
@@ -2197,15 +2214,15 @@ VALUES ('New York', NULL, NULL, 'NY');
    data modification, or schema modification
    (e.g., SELECT, UPDATE, DELETE,
    most variants of ALTER TABLE, but
-   not INSERT and ALTER TABLE ...
+   not INSERT or ALTER TABLE ...
    RENAME) typically default to including child tables and
    support the ONLY notation to exclude them.
    Commands that do database maintenance and tuning
    (e.g., REINDEX, VACUUM)
-   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 ().
+   behavior of each individual command is documented in its reference
+   page ().
   
 
   
@@ -2255,18 +2272,6 @@ VALUES ('New York', NULL, NULL, 'NY');
    inheritance is useful for your application.
   
 
-  
-   Deprecated
-   
-     In releases of PostgreSQL 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
-      configuration
-     option.
-   
-  
-
    
   
 

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 1e29852b40ebfea1f43859dc9e0d3343532f59a8..80fbc096c1b8834ebc13709e9046ddf413fecbfd 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -140,6 +140,16 @@ FROM table_reference , table_r
     — any columns added in subtables are ignored.
    
 
+   
+    Instead of writing ONLY before the table name, you can write
+    * after the table name to explicitly specify that descendant
+    tables are included.  Writing * is not necessary since that
+    behavior is the default (unless you have changed the setting of the 
+    linkend="guc-sql-inheritance"> configuration option).  However writing
+    * might be useful to emphasize that additional tables will be
+    searched.
+   
+
    
     Joined Tables
 


diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml

index a9fc887c778f5e526cc76c5597b44a845c25acd6..94343f88f6ead28261c44170f3fb3a24c5232555 100644 (file)

--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -490,10 +490,12 @@ ALTER TABLE name
       name
       
        
-        The name (possibly schema-qualified) of an existing table to
-        alter. If ONLY is specified, only that table is
-        altered. If ONLY is not specified, the table and any
-        descendant tables are altered.
+        The name (optionally schema-qualified) of an existing table to
+        alter. If ONLY is specified before the table name, only
+        that table is altered. If ONLY is not specified, the table
+        and all its descendant tables (if any) are altered.  Optionally,
+        * can be specified after the table name to explicitly
+        indicate that descendant tables are included.
        
       
      
@@ -877,7 +879,7 @@ ALTER TABLE distributors DROP CONSTRAINT zipchk;
   
 
   
-   To remove a check constraint from a table only:
+   To remove a check constraint from one table only:
 
 ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
 


diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml

index 84bf6bd23f94cdb0614936963625e326d65cf7f5..6c641b0b30a4ccfaae038528d1e475af38159673 100644 (file)

--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-DELETE FROM [ ONLY ] table [ [ AS ] alias ]
+DELETE FROM [ ONLY ] table [ * ] [ [ AS ] alias ]
     [ USING using_list ]
     [ WHERE condition | WHERE CURRENT OF cursor_name ]
     [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
@@ -46,13 +46,6 @@ DELETE FROM [ ONLY ] table [ [ AS ]
     
    
 
-  
-   By default, DELETE 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
-   ONLY clause.
-  
-
   
    There are two ways to delete rows in a table using information
    contained in other tables in the database: using sub-selects, or
@@ -83,21 +76,17 @@ DELETE FROM [ ONLY ] table [ [ AS ]
   Parameters
 
   
-   
-    ONLY
-    
-     
-      If specified, delete rows from the named table only.  When not
-      specified, any tables inheriting from the named table are also processed.
-     
-    
-   
-
    
     table
     
      
-      The name (optionally schema-qualified) of an existing table.
+      The name (optionally schema-qualified) of the table to delete rows
+      from.  If ONLY is specified before the table name,
+      matching rows are deleted from the named table only.  If
+      ONLY is not specified, matching rows are also deleted
+      from any tables inheriting from the named table.  Optionally,
+      * can be specified after the table name to explicitly
+      indicate that descendant tables are included.
      
     
    


diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml

index a61cb98c7a339990263a018c7d29aee031a30ef0..a7f7551c566bc5e4879ace080cbd7032cbafdcf4 100644 (file)

--- a/doc/src/sgml/ref/lock.sgml
+++ b/doc/src/sgml/ref/lock.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-LOCK [ TABLE ] [ ONLY ] name [, ...] [ IN lockmode MODE ] [ NOWAIT ]
+LOCK [ TABLE ] [ ONLY ] name [ * ] [, ...] [ IN lockmode MODE ] [ NOWAIT ]
 
 where lockmode is one of:
 
@@ -109,9 +109,11 @@ LOCK [ TABLE ] [ ONLY ] name [, ...
     
      
       The name (optionally schema-qualified) of an existing table to
-      lock.  If ONLY is specified, only that table is
-      locked.  If ONLY is not specified, the table and all
-      its descendant tables (if any) are locked.
+      lock. If ONLY is specified before the table name, only that
+      table is locked. If ONLY is not specified, the table and all
+      its descendant tables (if any) are locked.  Optionally, *
+      can be specified after the table name to explicitly indicate that
+      descendant tables are included.
      
 
      


diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml

index 3fbfda309e268ac53adf3097d9550a06b3acdcc1..0297415bdc6c88e7cce0fc7ead7d28a3a4e6dd6a 100644 (file)

--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -268,10 +268,12 @@ TABLE { [ ONLY ] table_name [ * ] |
       table_name
       
        
-        The name (optionally schema-qualified) of an existing table or
-        view.  If ONLY is specified, only that table is
-        scanned.  If ONLY is not specified, the table and
-        any descendant tables are scanned.
+        The name (optionally schema-qualified) of an existing table or view.
+        If ONLY is specified before the table name, only that
+        table is scanned.  If ONLY is not specified, the table
+        and all its descendant tables (if any) are scanned.  Optionally,
+        * can be specified after the table name to explicitly
+        indicate that descendant tables are included.
        
       
      
@@ -1555,15 +1557,24 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
   
 
   
-   <literal>ONLY</literal> and <span class="marked">Parentheses</span>
+   <literal>ONLY</literal> and <span class="marked">Inheritance</span>
 
    
-    The SQL standard requires parentheses around the table name
-    after ONLY, as in SELECT * FROM ONLY
-    (tab1), ONLY (tab2) WHERE ....  PostgreSQL supports that
-    as well, but the parentheses are optional.  (This point applies
-    equally to all SQL commands supporting the ONLY
-    option.)
+    The SQL standard requires parentheses around the table name when
+    writing ONLY, for example SELECT * FROM ONLY
+    (tab1), ONLY (tab2) WHERE ....  PostgreSQL
+    considers these parentheses to be optional.
+   
+
+   
+    PostgreSQL allows a trailing * to be written to
+    explicitly specify the non-ONLY behavior of including
+    child tables.  The standard does not allow this.
+   
+
+   
+    (These points apply equally to all SQL commands supporting the
+    ONLY option.)
    
   
 


diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml

index 08dc670843aaaf21688fabc6baf7801af0cced21..99202de5b498cdbaae58499593e3b595a8a3676c 100644 (file)

--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-TRUNCATE [ TABLE ] [ ONLY ] name [, ... ]
+TRUNCATE [ TABLE ] [ ONLY ] name [ * ] [, ... ]
     [ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ]
 
  
@@ -47,10 +47,12 @@ TRUNCATE [ TABLE ] [ ONLY ] name [,
     name
     
      
-      The name (optionally schema-qualified) of a table to be
-      truncated.  If ONLY is specified, only that table is
-      truncated.  If 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 ONLY is specified before the table name, only that table
+      is truncated.  If ONLY is not specified, the table and all
+      its descendant tables (if any) are truncated.  Optionally, *
+      can be specified after the table name to explicitly indicate that
+      descendant tables are included.
      
     
    


diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml

index 8673df18ff4d3cb10d3945b817f3ef63165366e5..10045c1683b05adeca281110a04b86a65d611fe4 100644 (file)

--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-UPDATE [ ONLY ] table [ [ AS ] alias ]
+UPDATE [ ONLY ] table [ * ] [ [ AS ] alias ]
     SET { column = { expression | DEFAULT } |
           ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...]
     [ FROM from_list ]
@@ -40,13 +40,6 @@ UPDATE [ ONLY ] table [ [ AS ] 
    columns not explicitly modified retain their previous values.
   
 
-  
-   By default, UPDATE 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 ONLY
-   clause.
-  
-
   
    There are two ways to modify a table using information contained in
    other tables in the database: using sub-selects, or specifying
@@ -84,6 +77,11 @@ UPDATE [ ONLY ] table [ [ AS ] 
     
      
       The name (optionally schema-qualified) of the table to update.
+      If ONLY is specified before the table name, matching rows
+      are updated in the named table only.  If ONLY is not
+      specified, matching rows are also updated in any tables inheriting from
+      the named table.  Optionally, * can be specified after the
+      table name to explicitly indicate that descendant tables are included.
      
     
    

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index a9fc887c778f5e526cc76c5597b44a845c25acd6..94343f88f6ead28261c44170f3fb3a24c5232555 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -490,10 +490,12 @@ ALTER TABLE name
       name
       
        
-        The name (possibly schema-qualified) of an existing table to
-        alter. If ONLY is specified, only that table is
-        altered. If ONLY is not specified, the table and any
-        descendant tables are altered.
+        The name (optionally schema-qualified) of an existing table to
+        alter. If ONLY is specified before the table name, only
+        that table is altered. If ONLY is not specified, the table
+        and all its descendant tables (if any) are altered.  Optionally,
+        * can be specified after the table name to explicitly
+        indicate that descendant tables are included.
        
       
      
@@ -877,7 +879,7 @@ ALTER TABLE distributors DROP CONSTRAINT zipchk;
   
 
   
-   To remove a check constraint from a table only:
+   To remove a check constraint from one table only:
 
 ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
 

diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index 84bf6bd23f94cdb0614936963625e326d65cf7f5..6c641b0b30a4ccfaae038528d1e475af38159673 100644 (file)
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-DELETE FROM [ ONLY ] table [ [ AS ] alias ]
+DELETE FROM [ ONLY ] table [ * ] [ [ AS ] alias ]
     [ USING using_list ]
     [ WHERE condition | WHERE CURRENT OF cursor_name ]
     [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
@@ -46,13 +46,6 @@ DELETE FROM [ ONLY ] table [ [ AS ]
     
    
 
-  
-   By default, DELETE 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
-   ONLY clause.
-  
-
   
    There are two ways to delete rows in a table using information
    contained in other tables in the database: using sub-selects, or
@@ -83,21 +76,17 @@ DELETE FROM [ ONLY ] table [ [ AS ]
   Parameters
 
   
-   
-    ONLY
-    
-     
-      If specified, delete rows from the named table only.  When not
-      specified, any tables inheriting from the named table are also processed.
-     
-    
-   
-
    
     table
     
      
-      The name (optionally schema-qualified) of an existing table.
+      The name (optionally schema-qualified) of the table to delete rows
+      from.  If ONLY is specified before the table name,
+      matching rows are deleted from the named table only.  If
+      ONLY is not specified, matching rows are also deleted
+      from any tables inheriting from the named table.  Optionally,
+      * can be specified after the table name to explicitly
+      indicate that descendant tables are included.
      
     
    

diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml
index a61cb98c7a339990263a018c7d29aee031a30ef0..a7f7551c566bc5e4879ace080cbd7032cbafdcf4 100644 (file)
--- a/doc/src/sgml/ref/lock.sgml
+++ b/doc/src/sgml/ref/lock.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-LOCK [ TABLE ] [ ONLY ] name [, ...] [ IN lockmode MODE ] [ NOWAIT ]
+LOCK [ TABLE ] [ ONLY ] name [ * ] [, ...] [ IN lockmode MODE ] [ NOWAIT ]
 
 where lockmode is one of:
 
@@ -109,9 +109,11 @@ LOCK [ TABLE ] [ ONLY ] name [, ...
     
      
       The name (optionally schema-qualified) of an existing table to
-      lock.  If ONLY is specified, only that table is
-      locked.  If ONLY is not specified, the table and all
-      its descendant tables (if any) are locked.
+      lock. If ONLY is specified before the table name, only that
+      table is locked. If ONLY is not specified, the table and all
+      its descendant tables (if any) are locked.  Optionally, *
+      can be specified after the table name to explicitly indicate that
+      descendant tables are included.
      
 
      

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 3fbfda309e268ac53adf3097d9550a06b3acdcc1..0297415bdc6c88e7cce0fc7ead7d28a3a4e6dd6a 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -268,10 +268,12 @@ TABLE { [ ONLY ] table_name [ * ] |
       table_name
       
        
-        The name (optionally schema-qualified) of an existing table or
-        view.  If ONLY is specified, only that table is
-        scanned.  If ONLY is not specified, the table and
-        any descendant tables are scanned.
+        The name (optionally schema-qualified) of an existing table or view.
+        If ONLY is specified before the table name, only that
+        table is scanned.  If ONLY is not specified, the table
+        and all its descendant tables (if any) are scanned.  Optionally,
+        * can be specified after the table name to explicitly
+        indicate that descendant tables are included.
        
       
      
@@ -1555,15 +1557,24 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
   
 
   
-   <literal>ONLY</literal> and <span class="marked">Parentheses</span>
+   <literal>ONLY</literal> and <span class="marked">Inheritance</span>
 
    
-    The SQL standard requires parentheses around the table name
-    after ONLY, as in SELECT * FROM ONLY
-    (tab1), ONLY (tab2) WHERE ....  PostgreSQL supports that
-    as well, but the parentheses are optional.  (This point applies
-    equally to all SQL commands supporting the ONLY
-    option.)
+    The SQL standard requires parentheses around the table name when
+    writing ONLY, for example SELECT * FROM ONLY
+    (tab1), ONLY (tab2) WHERE ....  PostgreSQL
+    considers these parentheses to be optional.
+   
+
+   
+    PostgreSQL allows a trailing * to be written to
+    explicitly specify the non-ONLY behavior of including
+    child tables.  The standard does not allow this.
+   
+
+   
+    (These points apply equally to all SQL commands supporting the
+    ONLY option.)
    
   
 

diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 08dc670843aaaf21688fabc6baf7801af0cced21..99202de5b498cdbaae58499593e3b595a8a3676c 100644 (file)
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-TRUNCATE [ TABLE ] [ ONLY ] name [, ... ]
+TRUNCATE [ TABLE ] [ ONLY ] name [ * ] [, ... ]
     [ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ]
 
  
@@ -47,10 +47,12 @@ TRUNCATE [ TABLE ] [ ONLY ] name [,
     name
     
      
-      The name (optionally schema-qualified) of a table to be
-      truncated.  If ONLY is specified, only that table is
-      truncated.  If 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 ONLY is specified before the table name, only that table
+      is truncated.  If ONLY is not specified, the table and all
+      its descendant tables (if any) are truncated.  Optionally, *
+      can be specified after the table name to explicitly indicate that
+      descendant tables are included.
      
     
    

diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 8673df18ff4d3cb10d3945b817f3ef63165366e5..10045c1683b05adeca281110a04b86a65d611fe4 100644 (file)
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  
 
-UPDATE [ ONLY ] table [ [ AS ] alias ]
+UPDATE [ ONLY ] table [ * ] [ [ AS ] alias ]
     SET { column = { expression | DEFAULT } |
           ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...]
     [ FROM from_list ]
@@ -40,13 +40,6 @@ UPDATE [ ONLY ] table [ [ AS ] 
    columns not explicitly modified retain their previous values.
   
 
-  
-   By default, UPDATE 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 ONLY
-   clause.
-  
-
   
    There are two ways to modify a table using information contained in
    other tables in the database: using sub-selects, or specifying
@@ -84,6 +77,11 @@ UPDATE [ ONLY ] table [ [ AS ] 
     
      
       The name (optionally schema-qualified) of the table to update.
+      If ONLY is specified before the table name, matching rows
+      are updated in the named table only.  If ONLY is not
+      specified, matching rows are also updated in any tables inheriting from
+      the named table.  Optionally, * can be specified after the
+      table name to explicitly indicate that descendant tables are included.