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>

Author: tglsfdc

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
-   <literal>CASCADE</literal> option.
+   <literal>CASCADE</literal> option (see <xref linkend="ddl-depend">).
   </para>
 
   <para>
@@ -3586,20 +3586,22 @@ HINT:  Use DROP ... CASCADE to drop the dependent objects too.
 <screen>
 DROP TABLE products CASCADE;
 </screen>
-   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 <command>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 <command>DROP ... CASCADE</> will do,
    run <command>DROP</> without <literal>CASCADE</> and read the
    <literal>DETAIL</> output.)
   </para>
 
   <para>
-   All <command>DROP</> commands in <productname>PostgreSQL</> support
+   Almost all <command>DROP</> commands in <productname>PostgreSQL</> support
    specifying <literal>CASCADE</literal>.  Of course, the nature of
    the possible dependencies varies with the type of the object.  You
    can also write <literal>RESTRICT</literal> instead of
    <literal>CASCADE</literal> 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.
   </para>
 
   <note>
@@ -3613,6 +3615,15 @@ DROP TABLE products CASCADE;
    </para>
   </note>
 
+  <para>
+   If a <command>DROP</> command lists multiple
+   objects, <literal>CASCADE</literal> is only required when there are
+   dependencies outside the specified group.  For example, when saying
+   <literal>DROP TABLE tab1, tab2</literal> the existence of a foreign
+   key referencing <literal>tab1</> from <literal>tab2</> would not mean
+   that <literal>CASCADE</literal> is needed to succeed.
+  </para>
+
   <para>
    For user-defined functions, <productname>PostgreSQL</productname> tracks
    dependencies associated with a function's externally-visible properties,

doc/src/sgml/ref/alter_domain.sgml

@@ -212,7 +212,9 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
       <term><literal>CASCADE</literal></term>
       <listitem>
        <para>
-        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 <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/alter_foreign_table.sgml

@@ -431,7 +431,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab
       <listitem>
        <para>
         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 <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/alter_table.sgml

@@ -823,7 +823,9 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
       <listitem>
        <para>
         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 <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/drop_access_method.sgml

@@ -62,7 +62,9 @@ DROP ACCESS METHOD [ IF EXISTS ] <replaceable class="parameter">name</replaceabl
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_aggregate.sgml

@@ -107,7 +107,10 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_collation.sgml

@@ -60,7 +60,9 @@ DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRIC
      <term><literal>CASCADE</literal></term>
      <listitem>
       <para>
-       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 <xref linkend="ddl-depend">).
       </para>
      </listitem>
     </varlistentry>

doc/src/sgml/ref/drop_domain.sgml

@@ -62,7 +62,9 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, .
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_event_trigger.sgml

@@ -63,7 +63,9 @@ DROP EVENT TRIGGER [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceabl
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_extension.sgml

@@ -66,7 +66,9 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_foreign_data_wrapper.sgml

@@ -63,7 +63,9 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</rep
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>
@@ -72,7 +74,7 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</rep
     <term><literal>RESTRICT</literal></term>
     <listitem>
      <para>
-      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.
      </para>
     </listitem>

doc/src/sgml/ref/drop_foreign_table.sgml

@@ -59,7 +59,8 @@ DROP FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceabl
     <listitem>
      <para>
       Automatically drop objects that depend on the foreign table (such as
-      views).
+      views), and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_function.sgml

@@ -107,7 +107,9 @@ DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> (
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_index.sgml

@@ -84,7 +84,9 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <replaceable class="PARAMETER">name</r
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_language.sgml

@@ -74,7 +74,9 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <replaceable class="PARAMETER">name</
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_materialized_view.sgml

@@ -64,7 +64,9 @@ DROP MATERIALIZED VIEW [ IF EXISTS ] <replaceable class="PARAMETER">name</replac
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_opclass.sgml

@@ -78,7 +78,9 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_operator.sgml

@@ -83,7 +83,9 @@ DROP OPERATOR [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> (
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_opfamily.sgml

@@ -79,7 +79,9 @@ DROP OPERATOR FAMILY [ IF EXISTS ] <replaceable class="PARAMETER">name</replacea
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_owned.sgml

@@ -55,7 +55,9 @@ DROP OWNED BY { <replaceable class="PARAMETER">name</replaceable> | CURRENT_USER
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_policy.sgml

@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-DROP POLICY [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
+DROP POLICY [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable> [ CASCADE | RESTRICT ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -72,6 +72,18 @@ DROP POLICY [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ON <
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><literal>CASCADE</literal></term>
+    <term><literal>RESTRICT</literal></term>
+
+    <listitem>
+     <para>
+      These key words do not have any effect, since there are no
+      dependencies on policies.
+     </para>
+    </listitem>
+   </varlistentry>
+
   </variablelist>
  </refsect1>
 

doc/src/sgml/ref/drop_rule.sgml

@@ -71,7 +71,9 @@ DROP RULE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> ON <re
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_schema.sgml

@@ -67,7 +67,9 @@ DROP SCHEMA [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, .
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>
@@ -84,6 +86,15 @@ DROP SCHEMA [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, .
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   Using the <literal>CASCADE</literal> option might make the command
+   remove objects in other schemas besides the one(s) named.
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Examples</title>
 

doc/src/sgml/ref/drop_sequence.sgml

@@ -61,7 +61,9 @@ DROP SEQUENCE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [,
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_server.sgml

@@ -63,7 +63,9 @@ DROP SERVER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ CA
     <listitem>
      <para>
       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 <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_table.sgml

@@ -75,7 +75,9 @@ DROP TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ..
     <listitem>
      <para>
       Automatically drop objects that depend on the table (such as
-      views).
+      views),
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_transform.sgml

@@ -18,7 +18,7 @@
 
  <refsynopsisdiv>
 <synopsis>
-DROP TRANSFORM [ IF EXISTS ] FOR <replaceable>type_name</replaceable> LANGUAGE <replaceable>lang_name</replaceable>
+DROP TRANSFORM [ IF EXISTS ] FOR <replaceable>type_name</replaceable> LANGUAGE <replaceable>lang_name</replaceable> [ CASCADE | RESTRICT ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -74,7 +74,9 @@ DROP TRANSFORM [ IF EXISTS ] FOR <replaceable>type_name</replaceable> LANGUAGE <
      <term><literal>CASCADE</literal></term>
      <listitem>
       <para>
-       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 <xref linkend="ddl-depend">).
       </para>
      </listitem>
     </varlistentry>