From: Tom Lane Date: Fri, 12 Aug 2016 22:45:18 +0000 (-0400) Subject: Doc: clarify that DROP ... CASCADE is recursive. X-Git-Tag: REL9_6_RC1~49 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=499787819309293f3d2cd7219aee334a0e7d5069;p=postgresql Doc: clarify that DROP ... CASCADE is recursive. Apparently that's not obvious to everybody, so let's belabor the point. In passing, document that DROP POLICY has CASCADE/RESTRICT options (which it does, per gram.y) but they do nothing (I assume, anyway). Also update some long-obsolete commentary in gram.y. Discussion: <20160805104837.1412.84915@wrigleys.postgresql.org> --- diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 954c3a9b9e..a393813b38 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -2611,7 +2611,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); if they are inherited from any parent tables. If you wish to remove a table and all of its descendants, one easy way is to drop the parent table with the - CASCADE option. + CASCADE option (see ). @@ -3586,20 +3586,22 @@ HINT: Use DROP ... CASCADE to drop the dependent objects too. DROP TABLE products CASCADE; - and all the dependent objects will be removed. In this case, it - doesn't remove the orders table, it only removes the foreign key - constraint. (If you want to check what DROP ... CASCADE will do, + and all the dependent objects will be removed, as will any objects + that depend on them, recursively. In this case, it doesn't remove + the orders table, it only removes the foreign key constraint. + It stops there because nothing depends on the foreign key constraint. + (If you want to check what DROP ... CASCADE will do, run DROP without CASCADE and read the DETAIL output.) - All DROP commands in PostgreSQL support + Almost all DROP commands in PostgreSQL support specifying CASCADE. Of course, the nature of the possible dependencies varies with the type of the object. You can also write RESTRICT instead of CASCADE to get the default behavior, which is to - prevent the dropping of objects that other objects depend on. + prevent dropping objects that any other objects depend on. @@ -3613,6 +3615,15 @@ DROP TABLE products CASCADE; + + If a DROP command lists multiple + objects, CASCADE is only required when there are + dependencies outside the specified group. For example, when saying + DROP TABLE tab1, tab2 the existence of a foreign + key referencing tab1 from tab2 would not mean + that CASCADE is needed to succeed. + + For user-defined functions, PostgreSQL tracks dependencies associated with a function's externally-visible properties, diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml index ac9a5b3f87..74dda73c69 100644 --- a/doc/src/sgml/ref/alter_domain.sgml +++ b/doc/src/sgml/ref/alter_domain.sgml @@ -212,7 +212,9 @@ ALTER DOMAIN name CASCADE - Automatically drop objects that depend on the constraint. + Automatically drop objects that depend on the constraint, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml index 4329d43a1e..b1692842b2 100644 --- a/doc/src/sgml/ref/alter_foreign_table.sgml +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -431,7 +431,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] name Automatically drop objects that depend on the dropped column - or constraint (for example, views referencing the column). + or constraint (for example, views referencing the column), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 5ca211e5f8..6f51cbc896 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -823,7 +823,9 @@ ALTER TABLE ALL IN TABLESPACE name Automatically drop objects that depend on the dropped column - or constraint (for example, views referencing the column). + or constraint (for example, views referencing the column), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_access_method.sgml b/doc/src/sgml/ref/drop_access_method.sgml index b899c71e1a..8aa9197fe4 100644 --- a/doc/src/sgml/ref/drop_access_method.sgml +++ b/doc/src/sgml/ref/drop_access_method.sgml @@ -62,7 +62,9 @@ DROP ACCESS METHOD [ IF EXISTS ] name Automatically drop objects that depend on the access method - (such as operator classes, operator families, indexes). + (such as operator classes, operator families, and indexes), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index 37683e51ef..c27c5eadf9 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -107,7 +107,10 @@ DROP AGGREGATE [ IF EXISTS ] name ( aggr CASCADE - Automatically drop objects that depend on the aggregate function. + Automatically drop objects that depend on the aggregate function + (such as views using it), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_collation.sgml b/doc/src/sgml/ref/drop_collation.sgml index f00c88679b..2177d8e5d6 100644 --- a/doc/src/sgml/ref/drop_collation.sgml +++ b/doc/src/sgml/ref/drop_collation.sgml @@ -60,7 +60,9 @@ DROP COLLATION [ IF EXISTS ] name [ CASCADE | RESTRIC CASCADE - Automatically drop objects that depend on the collation. + Automatically drop objects that depend on the collation, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index 995d09ec8e..e14795e6a3 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -62,7 +62,9 @@ DROP DOMAIN [ IF EXISTS ] name [, . Automatically drop objects that depend on the domain (such as - table columns). + table columns), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_event_trigger.sgml b/doc/src/sgml/ref/drop_event_trigger.sgml index cf42e15061..6e3ee22d7b 100644 --- a/doc/src/sgml/ref/drop_event_trigger.sgml +++ b/doc/src/sgml/ref/drop_event_trigger.sgml @@ -63,7 +63,9 @@ DROP EVENT TRIGGER [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the trigger. + Automatically drop objects that depend on the trigger, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml index 3bb9d9cb4c..7438a08bb3 100644 --- a/doc/src/sgml/ref/drop_extension.sgml +++ b/doc/src/sgml/ref/drop_extension.sgml @@ -66,7 +66,9 @@ DROP EXTENSION [ IF EXISTS ] name [ CASCADE - Automatically drop objects that depend on the extension. + Automatically drop objects that depend on the extension, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml index e43e0bda8b..824d72c176 100644 --- a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml @@ -63,7 +63,9 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] name Automatically drop objects that depend on the foreign-data - wrapper (such as servers). + wrapper (such as foreign tables and servers), + and in turn all objects that depend on those objects + (see ). @@ -72,7 +74,7 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] nameRESTRICT - Refuse to drop the foreign-data wrappers if any objects depend + Refuse to drop the foreign-data wrapper if any objects depend on it. This is the default. diff --git a/doc/src/sgml/ref/drop_foreign_table.sgml b/doc/src/sgml/ref/drop_foreign_table.sgml index 3c6376413e..f9d1e459d2 100644 --- a/doc/src/sgml/ref/drop_foreign_table.sgml +++ b/doc/src/sgml/ref/drop_foreign_table.sgml @@ -59,7 +59,8 @@ DROP FOREIGN TABLE [ IF EXISTS ] name Automatically drop objects that depend on the foreign table (such as - views). + views), and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 51b8ede5fb..5883d13811 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -107,7 +107,9 @@ DROP FUNCTION [ IF EXISTS ] name ( Automatically drop objects that depend on the function (such as - operators or triggers). + operators or triggers), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index d66d30edf7..6fe108ded2 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -84,7 +84,9 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the index. + Automatically drop objects that depend on the index, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index defae43c1a..0facc62876 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -74,7 +74,9 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] name Automatically drop objects that depend on the language (such as - functions in the language). + functions in the language), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_materialized_view.sgml b/doc/src/sgml/ref/drop_materialized_view.sgml index f3ddfb06e8..36ec33ceb0 100644 --- a/doc/src/sgml/ref/drop_materialized_view.sgml +++ b/doc/src/sgml/ref/drop_materialized_view.sgml @@ -64,7 +64,9 @@ DROP MATERIALIZED VIEW [ IF EXISTS ] name Automatically drop objects that depend on the materialized view (such as - other materialized views, or regular views). + other materialized views, or regular views), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml index 2ee8f883b6..187a9a4d1f 100644 --- a/doc/src/sgml/ref/drop_opclass.sgml +++ b/doc/src/sgml/ref/drop_opclass.sgml @@ -78,7 +78,9 @@ DROP OPERATOR CLASS [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the operator class. + Automatically drop objects that depend on the operator class (such as + indexes), and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index 902e4f3fa6..13dd974f38 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -83,7 +83,9 @@ DROP OPERATOR [ IF EXISTS ] name ( CASCADE - Automatically drop objects that depend on the operator. + Automatically drop objects that depend on the operator (such as views + using it), and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_opfamily.sgml b/doc/src/sgml/ref/drop_opfamily.sgml index d665e93883..53bce22883 100644 --- a/doc/src/sgml/ref/drop_opfamily.sgml +++ b/doc/src/sgml/ref/drop_opfamily.sgml @@ -79,7 +79,9 @@ DROP OPERATOR FAMILY [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the operator family. + Automatically drop objects that depend on the operator family, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml index d03cc57845..81694b88e5 100644 --- a/doc/src/sgml/ref/drop_owned.sgml +++ b/doc/src/sgml/ref/drop_owned.sgml @@ -55,7 +55,9 @@ DROP OWNED BY { name | CURRENT_USER CASCADE - Automatically drop objects that depend on the affected objects. + Automatically drop objects that depend on the affected objects, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_policy.sgml b/doc/src/sgml/ref/drop_policy.sgml index e5eaaa785b..69c87c0ade 100644 --- a/doc/src/sgml/ref/drop_policy.sgml +++ b/doc/src/sgml/ref/drop_policy.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation -DROP POLICY [ IF EXISTS ] name ON table_name +DROP POLICY [ IF EXISTS ] name ON table_name [ CASCADE | RESTRICT ] @@ -72,6 +72,18 @@ DROP POLICY [ IF EXISTS ] name ON < + + CASCADE + RESTRICT + + + + These key words do not have any effect, since there are no + dependencies on policies. + + + + diff --git a/doc/src/sgml/ref/drop_rule.sgml b/doc/src/sgml/ref/drop_rule.sgml index 16ab2b1bb5..d4905a69c9 100644 --- a/doc/src/sgml/ref/drop_rule.sgml +++ b/doc/src/sgml/ref/drop_rule.sgml @@ -71,7 +71,9 @@ DROP RULE [ IF EXISTS ] name ON CASCADE - Automatically drop objects that depend on the rule. + Automatically drop objects that depend on the rule, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_schema.sgml b/doc/src/sgml/ref/drop_schema.sgml index e3071227fe..5b1697fff2 100644 --- a/doc/src/sgml/ref/drop_schema.sgml +++ b/doc/src/sgml/ref/drop_schema.sgml @@ -67,7 +67,9 @@ DROP SCHEMA [ IF EXISTS ] name [, . Automatically drop objects (tables, functions, etc.) that are - contained in the schema. + contained in the schema, + and in turn all objects that depend on those objects + (see ). @@ -84,6 +86,15 @@ DROP SCHEMA [ IF EXISTS ] name [, . + + Notes + + + Using the CASCADE option might make the command + remove objects in other schemas besides the one(s) named. + + + Examples diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index b0f9cddda7..f0e1edc81c 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -61,7 +61,9 @@ DROP SEQUENCE [ IF EXISTS ] name [, CASCADE - Automatically drop objects that depend on the sequence. + Automatically drop objects that depend on the sequence, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_server.sgml b/doc/src/sgml/ref/drop_server.sgml index 497d83fb4a..f08dd7767d 100644 --- a/doc/src/sgml/ref/drop_server.sgml +++ b/doc/src/sgml/ref/drop_server.sgml @@ -63,7 +63,9 @@ DROP SERVER [ IF EXISTS ] name [ CA Automatically drop objects that depend on the server (such as - user mappings). + user mappings), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index 4cb1f49b3a..94d28b06fb 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -75,7 +75,9 @@ DROP TABLE [ IF EXISTS ] name [, .. Automatically drop objects that depend on the table (such as - views). + views), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_transform.sgml b/doc/src/sgml/ref/drop_transform.sgml index 59ff87cfe4..698920a226 100644 --- a/doc/src/sgml/ref/drop_transform.sgml +++ b/doc/src/sgml/ref/drop_transform.sgml @@ -18,7 +18,7 @@ -DROP TRANSFORM [ IF EXISTS ] FOR type_name LANGUAGE lang_name +DROP TRANSFORM [ IF EXISTS ] FOR type_name LANGUAGE lang_name [ CASCADE | RESTRICT ] @@ -74,7 +74,9 @@ DROP TRANSFORM [ IF EXISTS ] FOR type_name LANGUAGE < CASCADE - Automatically drop objects that depend on the transform. + Automatically drop objects that depend on the transform, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml index 2067aefca2..d400b8383f 100644 --- a/doc/src/sgml/ref/drop_trigger.sgml +++ b/doc/src/sgml/ref/drop_trigger.sgml @@ -73,7 +73,9 @@ DROP TRIGGER [ IF EXISTS ] name ON CASCADE - Automatically drop objects that depend on the trigger. + Automatically drop objects that depend on the trigger, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_tsconfig.sgml b/doc/src/sgml/ref/drop_tsconfig.sgml index 831485e6a6..0096e0092d 100644 --- a/doc/src/sgml/ref/drop_tsconfig.sgml +++ b/doc/src/sgml/ref/drop_tsconfig.sgml @@ -64,7 +64,9 @@ DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name CASCADE - Automatically drop objects that depend on the text search configuration. + Automatically drop objects that depend on the text search configuration, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_tsdictionary.sgml b/doc/src/sgml/ref/drop_tsdictionary.sgml index 44b30cbe67..803abf8cba 100644 --- a/doc/src/sgml/ref/drop_tsdictionary.sgml +++ b/doc/src/sgml/ref/drop_tsdictionary.sgml @@ -64,7 +64,9 @@ DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the text search dictionary. + Automatically drop objects that depend on the text search dictionary, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_tsparser.sgml b/doc/src/sgml/ref/drop_tsparser.sgml index 789e807dbe..fa99720161 100644 --- a/doc/src/sgml/ref/drop_tsparser.sgml +++ b/doc/src/sgml/ref/drop_tsparser.sgml @@ -62,7 +62,9 @@ DROP TEXT SEARCH PARSER [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the text search parser. + Automatically drop objects that depend on the text search parser, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_tstemplate.sgml b/doc/src/sgml/ref/drop_tstemplate.sgml index ebf8136744..9d051eb619 100644 --- a/doc/src/sgml/ref/drop_tstemplate.sgml +++ b/doc/src/sgml/ref/drop_tstemplate.sgml @@ -63,7 +63,9 @@ DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] nameCASCADE - Automatically drop objects that depend on the text search template. + Automatically drop objects that depend on the text search template, + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 98c8a3cbef..2c7b8fe9f6 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -62,7 +62,9 @@ DROP TYPE [ IF EXISTS ] name [, ... Automatically drop objects that depend on the type (such as - table columns, functions, operators). + table columns, functions, and operators), + and in turn all objects that depend on those objects + (see ). diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 8b43be5360..40f2356188 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -62,7 +62,9 @@ DROP VIEW [ IF EXISTS ] name [, ... Automatically drop objects that depend on the view (such as - other views). + other views), + and in turn all objects that depend on those objects + (see ). diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y index 0cae44641f..6a0f7b393c 100644 --- a/src/backend/parser/gram.y +++ b/src/backend/parser/gram.y @@ -1126,9 +1126,9 @@ AlterUserSetStmt: * * Drop a postgresql DBMS role * - * XXX Ideally this would have CASCADE/RESTRICT options, but since a role - * might own objects in multiple databases, there is presently no way to - * implement either cascading or restricting. Caveat DBA. + * XXX Ideally this would have CASCADE/RESTRICT options, but a role + * might own objects in multiple databases, and there is presently no way to + * implement cascading to other databases. So we always behave as RESTRICT. *****************************************************************************/ DropRoleStmt: @@ -1152,9 +1152,7 @@ DropRoleStmt: * * Drop a postgresql DBMS user * - * XXX Ideally this would have CASCADE/RESTRICT options, but since a user - * might own objects in multiple databases, there is presently no way to - * implement either cascading or restricting. Caveat DBA. + * XXX As with DROP ROLE, no CASCADE/RESTRICT here. *****************************************************************************/ DropUserStmt: @@ -1220,7 +1218,7 @@ add_drop: ADD_P { $$ = +1; } * * Drop a postgresql group * - * XXX see above notes about cascading DROP USER; groups have same problem. + * XXX As with DROP ROLE, no CASCADE/RESTRICT here. *****************************************************************************/ DropGroupStmt: @@ -4574,6 +4572,8 @@ auth_ident: RoleSpec { $$ = $1; } * QUERY : * DROP USER MAPPING FOR auth_ident SERVER name * + * XXX you'd think this should have a CASCADE/RESTRICT option, even if it's + * only pro forma; but the SQL standard doesn't show one. ****************************************************************************/ DropUserMappingStmt: DROP USER MAPPING FOR auth_ident SERVER name