svn commit: r462850 - /db/derby/docs/trunk/src/ref/rrefsqlj81859.dita

[bp...@apache.org]

Author: bpendleton
Date: Wed Oct 11 09:51:00 2006
New Revision: 462850

URL: http://svn.apache.org/viewvc?view=rev&rev=462850
Log:
DERBY-1926: Provide documentation for ALTER TABLE DROP COLUMN

This patch updates the Derby reference guide's page on ALTER TABLE
to include information about the DROP COLUMN variant of ALTER TABLE.

The page on ALTER TABLE is getting a bit unwieldly; I didn't attempt
to restructure it as I have no particular brilliant idea for
improving it. I just added a section on DROP COLUMN together with
a few examples.


Modified:
    db/derby/docs/trunk/src/ref/rrefsqlj81859.dita

Modified: db/derby/docs/trunk/src/ref/rrefsqlj81859.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj81859.dita?view=diff&rev=462850&r1=462849&r2=462850
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj81859.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj81859.dita Wed Oct 11 09:51:00 2006
@@ -34,6 +34,7 @@
 <section><p>The ALTER TABLE statement allows you to:   <ul>
 <li>add a column to a table</li>
 <li>add a constraint to a table</li>
+<li>drop a column from a table</li>
 <li>drop an existing constraint from a table</li>
 <li>increase the width of a VARCHAR, CHAR VARYING, and CHARACTER VARYING column</li>
 <li>override row-level locking for the table (or drop the override)</li>
@@ -45,6 +46,7 @@
 {
     ADD COLUMN <i><xref href="rrefsqlj81859.dita#rrefsqlj81859/rrefaltercolumndef">column-definition</xref></i> |
     ADD <i><xref href="rrefsqlj13590.dita#rrefsqlj13590">CONSTRAINT clause</xref></i> |
+    DROP [ COLUMN ] column-name [ CASCADE | RESTRICT ]
     DROP { PRIMARY KEY | FOREIGN KEY constraint-name | UNIQUE 
 	 constraint-name | CHECK constraint-name | CONSTRAINT constraint-name }
     ALTER [ COLUMN ] <i><xref href="rrefsqlj81859.dita#rrefsqlj81859/rrefsqlj37860">column-alteration</xref></i> |
@@ -117,6 +119,33 @@
 </ul></p><p>For information on the syntax of constraints, see <xref href="rrefsqlj13590.dita#rrefsqlj13590"></xref>.
 Use the syntax for table-level constraint when adding a constraint with the
 ADD TABLE ADD CONSTRAINT syntax.</p></section>
+<section><title>Dropping columns</title><p>ALTER TABLE DROP COLUMN
+allows you to drop a column from a table.</p>
+<p>
+The keyword COLUMN is optional.</p>
+<p>The keywords CASCADE and RESTRICT are also optional.
+If you specify neither CASCADE nor RESTRICT, the default is CASCADE.</p>
+<p>
+If you specify RESTRICT, then the column drop will be rejected if it
+would cause a dependent schema object to become invalid.</p>
+<p>
+If you specify CASCADE, then the column drop should
+additionally drop other schema objects which have become invalid.</p>
+<p>
+The schema objects which can cause a DROP COLUMN RESTRICT to be rejected
+include: views, triggers, primary key constraints, foreign key constraints,
+unique key constraints, check constraints, and column privileges. If one of
+these types of objects depends on the column being dropped, DROP COLUMN
+RESTRICT will reject the statement.</p>
+<p>
+You may not drop the last (only) column in a table.</p>
+<p>
+DROP COLUMN is not allowed if sqlAuthorization is true (see DERBY-1909).</p>
+<p>
+CASCADE/RESTRICT doesn't consider whether the column being dropped is used
+in any indexes. When a column is dropped, it is removed from any indexes
+which contain it. If that column was the only column in the index, the
+entire index is dropped.</p></section>
 <section><title>Dropping constraints</title><p>ALTER TABLE DROP CONSTRAINT
 drops a constraint on an existing table. To drop an unnamed constraint, you
 must specify the generated constraint name stored in <i>SYS.SYSCONSTRAINTS</i> as
@@ -191,6 +220,11 @@
 -- columns you are including in the primary key have
 -- null data or duplicate values.</ph>
 ALTER TABLE Activities ADD PRIMARY KEY (city_id, activity);
+
+<ph>-- Drop the city_id column if there are no dependent objects:</ph>
+ALTER TABLE Cities DROP COLUMN city_id RESTRICT;
+<ph>-- Drop the city_id column, also dropping all dependent objects:</ph>
+ALTER TABLE Cities DROP COLUMN city_id CASCADE;
 
 <ph>-- Drop a primary key constraint from the CITIES table
 </ph>