- The mechanics of the :meth:`.ConnectionEvents.dbapi_error` handler

have been enhanced such that the function handler is now capable
of raising or returning a new exception object, which will replace
the exception normally being thrown by SQLAlchemy.
fixes #3076

2 files changed, 38 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index f3389ffda..074dd6e31 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -15,6 +15,16 @@
     :released:
 
     .. change::
+        :tags: feature, engine
+        :tickets: 3076
+        :versions: 1.0.0
+
+        The mechanics of the :meth:`.ConnectionEvents.dbapi_error` handler
+        have been enhanced such that the function handler is now capable
+        of raising or returning a new exception object, which will replace
+        the exception normally being thrown by SQLAlchemy.
+
+    .. change::
         :tags: bug, orm
         :tickets: 3108
         :versions: 1.0.0
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index 43830197e..b9c45642c 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -131,6 +131,34 @@ wishes to support the new feature should now call upon the ``._limit_clause``
 and ``._offset_clause`` attributes to receive the full SQL expression, rather
 than the integer value.
 
+.. _feature_3076:
+
+DBAPI Exceptions may be re-stated using events
+----------------------------------------------
+
+.. note::
+
+	this feature is also back-ported to SQLAlchemy 0.9.7.
+
+The :meth:`.ConnectionEvents.dbapi_error` handler may now be used to re-state
+the exception raised as an alternate, user-defined exception::
+
+    @event.listens_for(Engine, "dbapi_error")
+    def handle_exception(conn, cursor, statement, parameters, context, exception):
+        if isinstance(exception, psycopg2.OperationalError) and \
+            "failed" in str(exception):
+            raise MySpecialException("failed operation")
+
+The handler supports both raising an exception immediately, as well
+as being able to return the new exception such that the chain of event handling
+will continue, the next event handler receiving the new exception as
+its argument.
+
+:ticket:`3076`
+
+.. seealso::
+
+	:meth:`.ConnectionEvents.dbapi_error`
 
 Behavioral Improvements
 =======================