Included is an example of using savepoints in a non-trivial example.

Giving examples in the SQL command reference is hard because we don't
have conditionals at the SQL level.

Gavin Sherry

doc/src/sgml/ref/begin.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.31 2004/08/01 17:32:13 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/begin.sgml,v 1.32 2004/08/08 01:48:31 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -100,6 +100,9 @@ BEGIN [ WORK | TRANSACTION ]
   <para>
    Issuing <command>BEGIN</> when already inside a transaction block will
    provoke a warning message.  The state of the transaction is not affected.
+   To nest transactions within a transaction block, use savepoints 
+   (See <xref linkend="sql-start-transaction" endterm="sql-start-transaction-title">
+   for more information).
   </para>
  </refsect1>
 

doc/src/sgml/ref/update.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.29 2004/06/09 19:08:13 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.30 2004/08/08 01:48:31 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -187,6 +187,19 @@ UPDATE employees SET sales_count = sales_count + 1 FROM accounts
 <programlisting>
 UPDATE employees SET sales_count = sales_count + 1 WHERE id =
   (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation');
+</programlisting>
+
+   Attempt to insert a new stock item along with the quantity of stock. If
+   the item exists, update the stock count of the existing item. To do this,
+   use savepoints.
+<programlisting>
+BEGIN;
+SAVEPOINT sp1;
+INSERT INTO wines VALUES('Chateau Lafite 2003', '24');
+-- Check for unique violation on name
+ROLLBACK TO sp1;
+UPDATE wines SET stock = stock + 24 WHERE winename='Chateau Lafite 2003';
+COMMIT;
 </programlisting>
   </para>
  </refsect1>