Document the recently-understood hazard that a rollback can release row-level

locks that logically should not be released, because when a subtransaction
overwrites XMAX all knowledge of the previous lock state is lost.  It seems
unlikely that we will be able to fix this before 8.3...

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 282a7872ad91218b9bc0409a93dc17a95c241d77..dd5acde6b55fce51a99351f1dcf9fab98b360dca 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 
 
@@ -883,6 +883,31 @@ FOR SHARE [ OF table_name [, ...] ]
     individual table rows; for example they can't be used with aggregation.
    
 
+  
+   
+    Avoid locking a row and then modifying it within a later savepoint or
+    PL/pgSQL exception block.  A subsequent
+    rollback would cause the lock to be lost.  For example,
+
+BEGIN;
+SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
+SAVEPOINT s;
+UPDATE mytable SET ... WHERE key = 1;
+ROLLBACK TO s;
+
+    After the ROLLBACK, the row is effectively unlocked, rather
+    than returned to its pre-savepoint state of being locked but not modified.
+    This hazard occurs if a row locked in the current transaction is updated
+    or deleted, or if a shared lock is upgraded to exclusive: in all these
+    cases, the former lock state is forgotten.  If the transaction is then
+    rolled back to a state between the original locking command and the
+    subsequent change, the row will appear not to be locked at all.  This is
+    an implementation deficiency which will be addressed in a future release
+    of PostgreSQL.
+   
+  
+
+  
    
     It is possible for a SELECT command using both
     LIMIT and  FOR UPDATE/SHARE
@@ -894,6 +919,7 @@ FOR SHARE [ OF table_name [, ...] ]
     or updated so that it does not meet the query WHERE condition
     anymore, in which case it will not be returned.
    
+