diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 9591f7cd41f..7ac7b983855 100644 --- 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' inheritance - This controls the inheritance semantics. If turned off, - subtables are not included 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 98233866300..37f0cbfddb6 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1995,6 +1995,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 @@ -2182,18 +2199,6 @@ VALUES ('New York', NULL, NULL, 'NY'); inheritance is useful for your problem. - - 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 b5b5542d51a..027768baf41 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -139,6 +139,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 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 d6bf184d649..2a1cd0027d9 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -433,15 +433,12 @@ where action is one of: 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 all - its descendant tables (if any) are updated. * 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, ONLY was the - default behavior. The default can be altered by changing the - configuration parameter .) + 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. diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 6e3d9ff2c1f..81e77fdf39a 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -20,7 +20,7 @@ PostgreSQL documentation -DELETE FROM [ ONLY ] table [ [ AS ] alias ] +DELETE FROM [ ONLY ] table [ * ] [ [ AS ] alias ] [ USING usinglist ] [ WHERE condition | WHERE CURRENT OF cursor_name ] [ RETURNING * | output_expression [ AS output_name ] [, ...] ] @@ -45,13 +45,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 @@ -82,21 +75,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/select.sgml b/doc/src/sgml/ref/select.sgml index b000dbb1f5b..b3b6cfb2ec5 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -184,16 +184,12 @@ where from_item can be one of: 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 - all its descendant tables (if any) are scanned. * - 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, - ONLY was the default behavior.) The default - behavior can be modified by changing the configuration option. + 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. diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index ce05150073a..8f39a7d0c16 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -20,7 +20,7 @@ PostgreSQL documentation -UPDATE [ ONLY ] table [ [ AS ] alias ] +UPDATE [ ONLY ] table [ * ] [ [ AS ] alias ] SET { column = { expression | DEFAULT } | ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...] [ FROM fromlist ] @@ -39,13 +39,6 @@ UPDATE [ ONLY ] table [ [ AS ] - - 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 @@ -82,6 +75,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.