plpgsql does exceptions.

There are still some things that need refinement; in particular I fear
that the recognized set of error condition names probably has little in
common with what Oracle recognizes.  But it's a start.

Author: tglsfdc

doc/src/sgml/plpgsql.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.41 2004/07/11 23:26:51 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.42 2004/07/31 07:39:17 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -1796,6 +1796,101 @@ END LOOP;
      rather than the simple syntax error one might expect to get.
     </para>
     </note>
+   </sect2>
+
+   <sect2 id="plpgsql-error-trapping">
+    <title>Trapping Errors</title>
+
+    <para>
+     By default, any error occurring in a <application>PL/pgSQL</>
+     function aborts execution of the function, and indeed of the
+     surrounding transaction as well.  You can trap errors and recover
+     from them by using a <command>BEGIN</> block with an
+     <literal>EXCEPTION</> clause.  The syntax is an extension of the
+     normal syntax for a <command>BEGIN</> block:
+
+<synopsis>
+<optional> &lt;&lt;<replaceable>label</replaceable>&gt;&gt; </optional>
+<optional> DECLARE
+    <replaceable>declarations</replaceable> </optional>
+BEGIN
+    <replaceable>statements</replaceable>
+EXCEPTION
+    WHEN <replaceable>condition</replaceable> THEN
+        <replaceable>handler_statements</replaceable>
+    <optional> WHEN <replaceable>condition</replaceable> THEN
+                   <replaceable>handler_statements</replaceable>
+    ...
+    </optional>
+END;
+</synopsis>
+    </para>
+
+    <para>
+     If no error occurs, this form of block simply executes all the
+     <replaceable>statements</replaceable>, and then control passes
+     to the next statement after <literal>END</>.  But if an error
+     occurs within the <replaceable>statements</replaceable>, further
+     processing of the <replaceable>statements</replaceable> is
+     abandoned, and control passes to the <literal>EXCEPTION</> list.
+     The list is searched for the first <replaceable>condition</replaceable>
+     matching the error that occurred.  If a match is found, the
+     corresponding <replaceable>handler_statements</replaceable> are
+     executed, and then control passes to the next statement after
+     <literal>END</>.  If no match is found, the error propagates out
+     as though the <literal>EXCEPTION</> clause were not there at all:
+     the error can be caught by an enclosing block with
+     <literal>EXCEPTION</>, or if there is none it aborts processing
+     of the function.  The special condition name <literal>OTHERS</>
+     matches every error type except <literal>QUERY_CANCELED</>.
+     (It is possible, but usually not a good idea, to trap
+     <literal>QUERY_CANCELED</> by name.)
+    </para>
+
+    <para>
+     If a new error occurs within the selected
+     <replaceable>handler_statements</replaceable>, it cannot be caught
+     by this <literal>EXCEPTION</> clause, but is propagated out.
+     A surrounding <literal>EXCEPTION</> clause could catch it.
+    </para>
+
+    <para>
+     When an error is caught by an <literal>EXCEPTION</> clause,
+     the local variables of the <application>PL/pgSQL</> function
+     remain as they were when the error occurred, but all changes
+     to persistent database state within the block are rolled back.
+     As an example, consider this fragment:
+
+<programlisting>
+    INSERT INTO mytab(firstname, lastname) VALUES('Tom', 'Jones');
+    BEGIN
+        UPDATE mytab SET firstname = 'Joe' WHERE lastname = 'Jones';
+        x := x + 1;
+        y := x / 0;
+    EXCEPTION
+        WHEN division_by_zero THEN
+            RAISE NOTICE 'caught division_by_zero';
+            RETURN x;
+    END;
+</programlisting>
+
+     When control reaches the assignment to <literal>y</>, it will
+     fail with a <literal>division_by_zero</> error.  This will be caught by
+     the <literal>EXCEPTION</> clause.  The value returned in the
+     <command>RETURN</> statement will be the incremented value of
+     <literal>x</>, but the effects of the <command>UPDATE</> command will
+     have been rolled back.  The <command>INSERT</> command is not rolled
+     back, however, so the end result is that the database contains
+     <literal>Tom Jones</> not <literal>Joe Jones</>.
+    </para>
+
+    <tip>
+     <para>
+      A block containing an <literal>EXCEPTION</> clause is significantly
+      more expensive to enter and exit than a block without one.  Therefore,
+      don't use <literal>EXCEPTION</> without need.
+     </para>
+    </tip>
   </sect2>
   </sect1>
 
@@ -2120,11 +2215,11 @@ RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="pa
 </synopsis>
 
     Possible levels are <literal>DEBUG</literal>,
-    <literal>LOG</literal>,
+    <literal>LOG</literal>, <literal>INFO</literal>,
     <literal>NOTICE</literal>, <literal>WARNING</literal>,
     and <literal>EXCEPTION</literal>.
-    <literal>EXCEPTION</literal> raises an error and aborts the current
-    transaction; the other levels only generate messages of different
+    <literal>EXCEPTION</literal> raises an error (which normally aborts the
+    current transaction); the other levels only generate messages of different
     priority levels.
     Whether messages of a particular priority are reported to the client,
     written to the server log, or both is controlled by the
@@ -2164,28 +2259,11 @@ RAISE EXCEPTION 'Nonexistent ID --> %', user_id;
    </para>
 
     <para>
-     <productname>PostgreSQL</productname> does not have a very smart
-     exception handling model. Whenever the parser, planner/optimizer
-     or executor decide that a statement cannot be processed any longer,
-     the whole transaction gets aborted and the system jumps back
-     into the main loop to get the next command from the client application.
-    </para>
-
-    <para>
-     It is possible to hook into the error mechanism to notice that this
-     happens. But currently it is impossible to tell what really
-     caused the abort (data type format error, floating-point
-     error, parse error, etc.). And it is possible that the database server
-     is in an inconsistent state at this point so returning to the upper
-     executor or issuing more commands might corrupt the whole database.
-    </para>
-
-    <para>
-     Thus, the only thing <application>PL/pgSQL</application>
-     currently does when it encounters an abort during execution of a
-     function or trigger procedure is to add some fields to the message
-     telling in which function and where (line number and type of statement)
-     the error happened.  The error always stops execution of the function.
+     <command>RAISE EXCEPTION</command> presently always generates
+     the same SQLSTATE code, <literal>P0001</>, no matter what message
+     it is invoked with.  It is possible to trap this exception with
+     <literal>EXCEPTION ... WHEN RAISE_EXCEPTION THEN ...</> but there
+     is no way to tell one <command>RAISE</> from another.
     </para>
  </sect1>
 

src/backend/access/transam/xact.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/access/transam/xact.c,v 1.173 2004/07/28 14:23:27 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/access/transam/xact.c,v 1.174 2004/07/31 07:39:18 tgl Exp $
  *
  * NOTES
  *		Transaction aborts can now occur two ways:
@@ -1589,7 +1589,8 @@ CleanupTransaction(void)
 	 * State should still be TRANS_ABORT from AbortTransaction().
 	 */
 	if (s->state != TRANS_ABORT)
-		elog(FATAL, "CleanupTransaction and not in abort state");
+		elog(FATAL, "CleanupTransaction: unexpected state %s",
+			 TransStateAsString(s->state));
 
 	/*
 	 * do abort cleanup processing
@@ -1773,7 +1774,7 @@ CommitTransactionCommand(void)
 
 			/*
 			 * We were just issued a SAVEPOINT inside a transaction block.
-			 * Start a subtransaction.  (BeginTransactionBlock already
+			 * Start a subtransaction.  (DefineSavepoint already
 			 * did PushTransaction, so as to have someplace to put the
 			 * SUBBEGIN state.)
 			 */
@@ -1853,6 +1854,7 @@ CleanupAbortedSubTransactions(bool returnName)
 	AssertState(PointerIsValid(s->parent));
 	Assert(s->parent->blockState == TBLOCK_SUBINPROGRESS ||
 		   s->parent->blockState == TBLOCK_INPROGRESS ||
+		   s->parent->blockState == TBLOCK_STARTED ||
 		   s->parent->blockState == TBLOCK_SUBABORT_PENDING);
 
 	/*
@@ -1878,7 +1880,8 @@ CleanupAbortedSubTransactions(bool returnName)
 	}
 
 	AssertState(s->blockState == TBLOCK_SUBINPROGRESS ||
-				s->blockState == TBLOCK_INPROGRESS);
+				s->blockState == TBLOCK_INPROGRESS ||
+				s->blockState == TBLOCK_STARTED);
 
 	return name;
 }
@@ -2468,7 +2471,7 @@ DefineSavepoint(char *name)
 		case TBLOCK_SUBABORT_PENDING:
 		case TBLOCK_SUBENDABORT_RELEASE:
 		case TBLOCK_SUBEND:
-			elog(FATAL, "BeginTransactionBlock: unexpected state %s",
+			elog(FATAL, "DefineSavepoint: unexpected state %s",
 				 BlockStateAsString(s->blockState));
 			break;
 	}
@@ -2657,20 +2660,126 @@ RollbackToSavepoint(List *options)
 }
 
 /*
- * RollbackAndReleaseSavepoint
+ * BeginInternalSubTransaction
+ *		This is the same as DefineSavepoint except it allows TBLOCK_STARTED
+ *		state, and therefore it can safely be used in a function that might
+ *		be called when not inside a BEGIN block.  Also, we automatically
+ *		cycle through CommitTransactionCommand/StartTransactionCommand
+ *		instead of expecting the caller to do it.
+ *
+ * Optionally, name can be NULL to create an unnamed savepoint.
+ */
+void
+BeginInternalSubTransaction(char *name)
+{
+	TransactionState	s = CurrentTransactionState;
+
+	switch (s->blockState)
+	{
+		case TBLOCK_STARTED:
+		case TBLOCK_INPROGRESS:
+		case TBLOCK_SUBINPROGRESS:
+			/* Normal subtransaction start */
+			PushTransaction();
+			s = CurrentTransactionState;	/* changed by push */
+			/*
+			 * Note that we are allocating the savepoint name in the
+			 * parent transaction's CurTransactionContext, since we
+			 * don't yet have a transaction context for the new guy.
+			 */
+			if (name)
+				s->name = MemoryContextStrdup(CurTransactionContext, name);
+			s->blockState = TBLOCK_SUBBEGIN;
+			break;
+
+			/* These cases are invalid.  Reject them altogether. */
+		case TBLOCK_DEFAULT:
+		case TBLOCK_BEGIN:
+		case TBLOCK_SUBBEGIN:
+		case TBLOCK_ABORT:
+		case TBLOCK_SUBABORT:
+		case TBLOCK_ENDABORT:
+		case TBLOCK_END:
+		case TBLOCK_SUBENDABORT_ALL:
+		case TBLOCK_SUBENDABORT:
+		case TBLOCK_SUBABORT_PENDING:
+		case TBLOCK_SUBENDABORT_RELEASE:
+		case TBLOCK_SUBEND:
+			elog(FATAL, "BeginInternalSubTransaction: unexpected state %s",
+				 BlockStateAsString(s->blockState));
+			break;
+	}
+
+	CommitTransactionCommand();
+	StartTransactionCommand();
+}
+
+/*
+ * ReleaseCurrentSubTransaction
+ *
+ * RELEASE (ie, commit) the innermost subtransaction, regardless of its
+ * savepoint name (if any).
+ * NB: do NOT use CommitTransactionCommand/StartTransactionCommand with this.
+ */
+void
+ReleaseCurrentSubTransaction(void)
+{
+	TransactionState s = CurrentTransactionState;
+
+	if (s->blockState != TBLOCK_SUBINPROGRESS)
+		elog(ERROR, "ReleaseCurrentSubTransaction: unexpected state %s",
+			 BlockStateAsString(s->blockState));
+	MemoryContextSwitchTo(CurTransactionContext);
+	CommitTransactionToLevel(GetCurrentTransactionNestLevel());
+}
+
+/*
+ * RollbackAndReleaseCurrentSubTransaction
  *
- * Executes a ROLLBACK TO command, immediately followed by a RELEASE
- * of the same savepoint.
+ * ROLLBACK and RELEASE (ie, abort) the innermost subtransaction, regardless
+ * of its savepoint name (if any).
+ * NB: do NOT use CommitTransactionCommand/StartTransactionCommand with this.
  */
 void
-RollbackAndReleaseSavepoint(List *options)
+RollbackAndReleaseCurrentSubTransaction(void)
 {
-	TransactionState s;
+	TransactionState s = CurrentTransactionState;
 
-	RollbackToSavepoint(options);
-	s = CurrentTransactionState;
-	Assert(s->blockState == TBLOCK_SUBENDABORT);
+	switch (s->blockState)
+	{
+		/* Must be in a subtransaction */
+		case TBLOCK_SUBABORT:
+		case TBLOCK_SUBINPROGRESS:
+			break;
+
+			/* these cases are invalid. */
+		case TBLOCK_DEFAULT:
+		case TBLOCK_STARTED:
+		case TBLOCK_ABORT:
+		case TBLOCK_INPROGRESS:
+		case TBLOCK_BEGIN:
+		case TBLOCK_END:
+		case TBLOCK_ENDABORT:
+		case TBLOCK_SUBEND:
+		case TBLOCK_SUBENDABORT_ALL:
+		case TBLOCK_SUBENDABORT:
+		case TBLOCK_SUBABORT_PENDING:
+		case TBLOCK_SUBENDABORT_RELEASE:
+		case TBLOCK_SUBBEGIN:
+			elog(FATAL, "RollbackAndReleaseCurrentSubTransaction: unexpected state %s",
+				 BlockStateAsString(s->blockState));
+			break;
+	}
+
+	/*
+	 * Abort the current subtransaction, if needed.
+	 */
+	if (s->blockState == TBLOCK_SUBINPROGRESS)
+		AbortSubTransaction();
 	s->blockState = TBLOCK_SUBENDABORT_RELEASE;
+
+	/* And clean it up, too */
+	CleanupAbortedSubTransactions(false);
 }
 
 /*
@@ -2748,7 +2857,7 @@ AbortOutOfAnyTransaction(void)
  * Commit everything from the current transaction level
  * up to the specified level (inclusive).
  */
-void
+static void
 CommitTransactionToLevel(int level)
 {
 	TransactionState s = CurrentTransactionState;

src/include/access/xact.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/access/xact.h,v 1.67 2004/07/27 05:11:24 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/access/xact.h,v 1.68 2004/07/31 07:39:19 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -107,7 +107,9 @@ extern void UserAbortTransactionBlock(void);
 extern void ReleaseSavepoint(List *options);
 extern void DefineSavepoint(char *name);
 extern void RollbackToSavepoint(List *options);
-extern void RollbackAndReleaseSavepoint(List *options);
+extern void BeginInternalSubTransaction(char *name);
+extern void ReleaseCurrentSubTransaction(void);
+extern void RollbackAndReleaseCurrentSubTransaction(void);
 extern bool IsSubTransaction(void);
 extern bool IsTransactionBlock(void);
 extern bool IsTransactionOrTransactionBlock(void);

src/include/utils/errcodes.h

@@ -11,7 +11,7 @@
  *
  * Copyright (c) 2003, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/include/utils/errcodes.h,v 1.13 2004/07/27 05:11:35 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/utils/errcodes.h,v 1.14 2004/07/31 07:39:20 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -326,6 +326,10 @@
 #define ERRCODE_CONFIG_FILE_ERROR			MAKE_SQLSTATE('F','0', '0','0','0')
 #define ERRCODE_LOCK_FILE_EXISTS			MAKE_SQLSTATE('F','0', '0','0','1')
 
+/* Class P0 - PL/pgSQL Error (PostgreSQL-specific error class) */
+#define ERRCODE_PLPGSQL_ERROR				MAKE_SQLSTATE('P','0', '0','0','0')
+#define ERRCODE_RAISE_EXCEPTION				MAKE_SQLSTATE('P','0', '0','0','1')
+
 /* Class XX - Internal Error (PostgreSQL-specific error class) */
 /* (this is for "can't-happen" conditions and software bugs) */
 #define ERRCODE_INTERNAL_ERROR				MAKE_SQLSTATE('X','X', '0','0','0')