Warn more vigorously about the non-transactional behavior of sequences.

Craig Ringer, edited fairly heavily by me

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index afc82a25baf12cf7009ab4ac08e84f7245aa4ccf..aed2d96bedcc849ff2f70352294d2c7bfc7cadb4 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -829,6 +829,20 @@ ALTER SEQUENCE tablename_
      the column, so that it will be dropped if the column or table is dropped.
     
 
+    
+      
+        Because smallserial, serial and
+        bigserial are implemented usings sequences, there may
+        be "holes" or gaps in the sequence of values which appears in the
+        column, even if no rows are ever deleted.  This is a value allocated
+        from the sequence is still "used up" even if a row containing that
+        value is never successfully inserted into the table column.  This
+        may happen, for example, if the inserting transaction rolls back.
+        See nextval() in 
+        for details.
+      
+    
+
     
      
       Prior to PostgreSQL 7.3, serial

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 157de09b4ea213156679dd62a121bc0274f4c127..ee42da80257dcb03d0a41d2f59222ed24011690b 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -9820,6 +9820,27 @@ nextval('foo'::text)      foo is looked up at
         execute nextval concurrently, each will safely receive
         a distinct sequence value.
        
+
+       
+        If a sequence object has been created with default parameters,
+        successive nextval calls will return successive
+        values beginning with 1.  Other behaviors can be obtained by using
+        special parameters in the  command;
+        see its command reference page for more information.
+       
+
+       
+        
+         To avoid blocking concurrent transactions that obtain numbers from the
+         same sequence, a nextval operation is never
+         rolled back; that is, once a value has been fetched it is considered
+         used, even if the transaction that did the
+         nextval later aborts.  This means that aborted
+         transactions might leave unused holes in the sequence
+         of assigned values.
+        
+       
+
       
      
 
@@ -9883,31 +9904,18 @@ SELECT setval('foo', 42, false);    Next nextval wi
         The result returned by setval is just the value of its
         second argument.
        
+       
+        
+         Because sequences are non-transactional, changes made by
+         setval are not undone if the transaction rolls
+         back.
+        
+       
       
      
     
   
 
-  
-   If a sequence object has been created with default parameters,
-   successive nextval calls will return successive values
-   beginning with 1.  Other behaviors can be obtained by using
-   special parameters in the  command;
-   see its command reference page for more information.
-  
-
-  
-   
-    To avoid blocking concurrent transactions that obtain numbers from the
-    same sequence, a nextval operation is never rolled back;
-    that is, once a value has been fetched it is considered used, even if the
-    transaction that did the nextval later aborts.  This means
-    that aborted transactions might leave unused holes in the
-    sequence of assigned values.  setval operations are never
-    rolled back, either.
-   
-  
-