Update ALTER TABLE docs to mention using VACUUM FULL for rewrites.

Remove the claim that ALTER TABLE .. SET DATA TYPE is the fastest way of
rewriting a table, since it no longer is.

Noah Misch and Robert Haas, based on a suggestion from Tom Lane.

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1d52be6a73d6ac1230eb52fbfd6a6f70bab311d7..52f70cea18ee1f1705a798eb985231155525fd71 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -403,9 +403,9 @@ ALTER TABLE name
       for details on the available parameters.  Note that the table contents
       will not be modified immediately by this command; depending on the
       parameter you might need to rewrite the table to get the desired effects.
-      That can be done with <xref linkend="SQL-CLUSTER">
-      or one of the forms of ALTER
-      TABLE that forces a table rewrite.
+      That can be done with <link linkend="SQL-VACUUM">VACUUM
+      FULL,  or one of the forms
+      of ALTER TABLE that forces a table rewrite.
      
 
      
@@ -777,18 +777,11 @@ ALTER TABLE name
    
 
    
-    The fact that SET DATA TYPE requires rewriting the whole table
-    is sometimes an advantage, because the rewriting process eliminates
-    any dead space in the table.  For example, to reclaim the space occupied
-    by a dropped column immediately, the fastest way is:
-
-ALTER TABLE table ALTER COLUMN anycol TYPE anytype;
-
-    where anycol is any remaining table column and
-    anytype is the same type that column already has.
-    This results in no semantically-visible change in the table,
-    but the command forces rewriting, which gets rid of no-longer-useful
-    data.
+    To force an immediate rewrite of the table, you can use
+    VACUUM FULL, 
+    or one of the forms of ALTER TABLE that forces a rewrite, such as
+    SET DATA TYPE.  This results in no semantically-visible change in the
+    table, but gets rid of no-longer-useful data.