Skip to content

Commit 4997878

Browse files
tglsfdctglsfdc
committed
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>
1 parent 4b234fd commit 4997878

35 files changed

+144
-48
lines changed

‎doc/src/sgml/ddl.sgml

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2611,7 +2611,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
26112611
if they are inherited
26122612
from any parent tables. If you wish to remove a table and all of its
26132613
descendants, one easy way is to drop the parent table with the
2614-
<literal>CASCADE</literal> option.
2614+
<literal>CASCADE</literal> option (see <xref linkend="ddl-depend">).
26152615
</para>
26162616

26172617
<para>
@@ -3586,20 +3586,22 @@ HINT: Use DROP ... CASCADE to drop the dependent objects too.
35863586
<screen>
35873587
DROP TABLE products CASCADE;
35883588
</screen>
3589-
and all the dependent objects will be removed. In this case, it
3590-
doesn't remove the orders table, it only removes the foreign key
3591-
constraint. (If you want to check what <command>DROP ... CASCADE</> will do,
3589+
and all the dependent objects will be removed, as will any objects
3590+
that depend on them, recursively. In this case, it doesn't remove
3591+
the orders table, it only removes the foreign key constraint.
3592+
It stops there because nothing depends on the foreign key constraint.
3593+
(If you want to check what <command>DROP ... CASCADE</> will do,
35923594
run <command>DROP</> without <literal>CASCADE</> and read the
35933595
<literal>DETAIL</> output.)
35943596
</para>
35953597

35963598
<para>
3597-
All <command>DROP</> commands in <productname>PostgreSQL</> support
3599+
Almost all <command>DROP</> commands in <productname>PostgreSQL</> support
35983600
specifying <literal>CASCADE</literal>. Of course, the nature of
35993601
the possible dependencies varies with the type of the object. You
36003602
can also write <literal>RESTRICT</literal> instead of
36013603
<literal>CASCADE</literal> to get the default behavior, which is to
3602-
prevent the dropping of objects that other objects depend on.
3604+
prevent dropping objects that any other objects depend on.
36033605
</para>
36043606

36053607
<note>
@@ -3613,6 +3615,15 @@ DROP TABLE products CASCADE;
36133615
</para>
36143616
</note>
36153617

3618+
<para>
3619+
If a <command>DROP</> command lists multiple
3620+
objects, <literal>CASCADE</literal> is only required when there are
3621+
dependencies outside the specified group. For example, when saying
3622+
<literal>DROP TABLE tab1, tab2</literal> the existence of a foreign
3623+
key referencing <literal>tab1</> from <literal>tab2</> would not mean
3624+
that <literal>CASCADE</literal> is needed to succeed.
3625+
</para>
3626+
36163627
<para>
36173628
For user-defined functions, <productname>PostgreSQL</productname> tracks
36183629
dependencies associated with a function's externally-visible properties,

‎doc/src/sgml/ref/alter_domain.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,9 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
212212
<term><literal>CASCADE</literal></term>
213213
<listitem>
214214
<para>
215-
Automatically drop objects that depend on the constraint.
215+
Automatically drop objects that depend on the constraint,
216+
and in turn all objects that depend on those objects
217+
(see <xref linkend="ddl-depend">).
216218
</para>
217219
</listitem>
218220
</varlistentry>

‎doc/src/sgml/ref/alter_foreign_table.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -431,7 +431,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab
431431
<listitem>
432432
<para>
433433
Automatically drop objects that depend on the dropped column
434-
or constraint (for example, views referencing the column).
434+
or constraint (for example, views referencing the column),
435+
and in turn all objects that depend on those objects
436+
(see <xref linkend="ddl-depend">).
435437
</para>
436438
</listitem>
437439
</varlistentry>

‎doc/src/sgml/ref/alter_table.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -823,7 +823,9 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
823823
<listitem>
824824
<para>
825825
Automatically drop objects that depend on the dropped column
826-
or constraint (for example, views referencing the column).
826+
or constraint (for example, views referencing the column),
827+
and in turn all objects that depend on those objects
828+
(see <xref linkend="ddl-depend">).
827829
</para>
828830
</listitem>
829831
</varlistentry>

‎doc/src/sgml/ref/drop_access_method.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@ DROP ACCESS METHOD [ IF EXISTS ] <replaceable class="parameter">name</replaceabl
6262
<listitem>
6363
<para>
6464
Automatically drop objects that depend on the access method
65-
(such as operator classes, operator families, indexes).
65+
(such as operator classes, operator families, and indexes),
66+
and in turn all objects that depend on those objects
67+
(see <xref linkend="ddl-depend">).
6668
</para>
6769
</listitem>
6870
</varlistentry>

‎doc/src/sgml/ref/drop_aggregate.sgml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,10 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr
107107
<term><literal>CASCADE</literal></term>
108108
<listitem>
109109
<para>
110-
Automatically drop objects that depend on the aggregate function.
110+
Automatically drop objects that depend on the aggregate function
111+
(such as views using it),
112+
and in turn all objects that depend on those objects
113+
(see <xref linkend="ddl-depend">).
111114
</para>
112115
</listitem>
113116
</varlistentry>

‎doc/src/sgml/ref/drop_collation.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,9 @@ DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRIC
6060
<term><literal>CASCADE</literal></term>
6161
<listitem>
6262
<para>
63-
Automatically drop objects that depend on the collation.
63+
Automatically drop objects that depend on the collation,
64+
and in turn all objects that depend on those objects
65+
(see <xref linkend="ddl-depend">).
6466
</para>
6567
</listitem>
6668
</varlistentry>

‎doc/src/sgml/ref/drop_domain.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, .
6262
<listitem>
6363
<para>
6464
Automatically drop objects that depend on the domain (such as
65-
table columns).
65+
table columns),
66+
and in turn all objects that depend on those objects
67+
(see <xref linkend="ddl-depend">).
6668
</para>
6769
</listitem>
6870
</varlistentry>

‎doc/src/sgml/ref/drop_event_trigger.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,9 @@ DROP EVENT TRIGGER [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceabl
6363
<term><literal>CASCADE</literal></term>
6464
<listitem>
6565
<para>
66-
Automatically drop objects that depend on the trigger.
66+
Automatically drop objects that depend on the trigger,
67+
and in turn all objects that depend on those objects
68+
(see <xref linkend="ddl-depend">).
6769
</para>
6870
</listitem>
6971
</varlistentry>

‎doc/src/sgml/ref/drop_extension.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,9 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [
6666
<term><literal>CASCADE</literal></term>
6767
<listitem>
6868
<para>
69-
Automatically drop objects that depend on the extension.
69+
Automatically drop objects that depend on the extension,
70+
and in turn all objects that depend on those objects
71+
(see <xref linkend="ddl-depend">).
7072
</para>
7173
</listitem>
7274
</varlistentry>

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy