This patch improves the documentation for SERIAL columns a little bit.

Neil Conway

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index cac65623dc5cc28c128f8cabe28e06006c931eb2..a837b31550a7f2fd3ce25c9601db38b5de8af093 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -654,10 +654,11 @@ NUMERIC
     
 
     
-     The serial data types are not truly types, but are a
-     notational convenience for setting up unique identifier columns
-     in tables.
-     In the current implementation, specifying
+     The serial data type is not a true type, but merely
+     a notational convenience for setting up identifier columns
+     (similar to the AUTO_INCREMENT property
+     supported by some other databases). In the current
+     implementation, specifying
 
 
 CREATE TABLE tablename (
@@ -683,33 +684,50 @@ CREATE TABLE tablename (
      not automatic.
     
 
+    
+     To use a serial column to insert the next value of
+     the sequence into the table, specify that the serial
+     column should be assigned the default value. This can be done
+     either be excluding from the column from the list of columns in
+     the INSERT statement, or through the use of
+     the DEFAULT keyword.
+    
+
     
      The type names serial and serial4 are
      equivalent: both create integer columns.  The type
      names bigserial and serial8 work just
      the same way, except that they create a bigint
      column.  bigserial should be used if you anticipate
-     the use of more than 231 identifiers over the lifetime of the table.
+     the use of more than 231 identifiers over the
+     lifetime of the table.
     
 
     
-     The sequence created by a serial type is automatically
-     dropped when
-     the owning column is dropped, and cannot be dropped otherwise.
-     (This was not true in PostgreSQL releases
-     before 7.3.  Note that this automatic drop linkage will not occur for a
-     sequence created by reloading a dump from a pre-7.3 database; the dump
-     file does not contain the information needed to establish the dependency
-     link.)
+     The sequence created by a serial type is
+     automatically dropped when the owning column is dropped, and
+     cannot be dropped otherwise.  (This was not true in
+     PostgreSQL releases before 7.3.  Note
+     that this automatic drop linkage will not occur for a sequence
+     created by reloading a dump from a pre-7.3 database; the dump
+     file does not contain the information needed to establish the
+     dependency link.) Furthermore, this dependency between sequence
+     and column is made only for the serial column itself; if
+     any other columns reference the sequence (perhaps by manually
+     calling the nextval()) function), they may be broken
+     if the sequence is removed. Using serial columns in
+     fashion is considered bad form.
     
 
-    
-     Prior to PostgreSQL 7.3, serial
-     implied UNIQUE.  This is no longer automatic.  If
-     you wish a serial column to be UNIQUE or a 
-     PRIMARY KEY it must now be specified, same as with
-     any other data type.
-    
+    
+     
+      Prior to PostgreSQL 7.3, serial
+      implied UNIQUE.  This is no longer automatic.
+      If you wish a serial column to be UNIQUE or a
+      PRIMARY KEY it must now be specified, just as
+      with any other data type.
+     
+