Document that plpgsql upsert example can fail if insert triggers return

unique exception, or if not used in read committed transaction mode.

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index c342916ff363ea952c497ae81575d1a944d89ad6..d2e74dca81e2d5c8d06f9e887fc4fcf931fed05d 100644 (file)
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2464,7 +2464,7 @@ BEGIN
             INSERT INTO db(a,b) VALUES (key, data);
             RETURN;
         EXCEPTION WHEN unique_violation THEN
-            -- do nothing, and loop to try the UPDATE again
+            -- Do nothing, and loop to try the UPDATE again.
         END;
     END LOOP;
 END;
@@ -2474,7 +2474,10 @@ LANGUAGE plpgsql;
 SELECT merge_db(1, 'david');
 SELECT merge_db(1, 'dennis');
 
-
+     This example assumes the unique_violation error is caused by
+     the INSERT, and not by an INSERT trigger function
+     on the table.  Also, this example only works in the default Read
+     Committed transaction mode.