indicate legacy ping recipe for handle_error cases

in prep for a new feature as part of #5648.

Change-Id: I6720b0ea797c188de5e8163f79fb7b7994d6e76e
(cherry picked from commit 41d3e16773e84692b6625ccb67da204b5362d9c3)

diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst
index fa32c4b4097fc1fe4d6e56596937ddd641046b1a..1197999402faf520caced788627f4417b25b7e89 100644 (file)
--- a/doc/build/core/pooling.rst
+++ b/doc/build/core/pooling.rst
@@ -212,6 +212,8 @@ to three times before giving up, propagating the database error last received.
 .. versionadded:: 1.2 Added "pre-ping" capability to the :class:`_pool.Pool`
    class.
 
+.. _pool_disconnects_pessimistic_custom:
+
 Custom / Legacy Pessimistic Ping
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index e57ec6847186b7a795b0947e0f6f6529f556ca4e..d9dac0600c6955d4724e28486f2228e443f2919d 100644 (file)
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -1447,6 +1447,16 @@ class ExceptionContext(object):
     a connection and pool invalidation can be invoked or prevented by
     changing this flag.
 
+
+    .. note:: The pool "pre_ping" handler enabled using the
+        :paramref:`_sa.create_engine.pool_pre_ping` parameter does **not**
+        consult this event before deciding if the "ping" returned false,
+        as opposed to receiving an unhandled error.   For this use case, the
+        :ref:`legacy recipe based on engine_connect() may be used
+        <pool_disconnects_pessimistic_custom>`.  A future API allow more
+        comprehensive customization of the "disconnect" detection mechanism
+        across all functions.
+
     """
 
     invalidate_pool_on_disconnect = True

diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index 3a758d60363f3cd8b62be6f575c59c387f49f554..1fe732b2a6d13cd96150e7dd168af2a2b55b8c8a 100644 (file)
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -844,7 +844,7 @@ class ConnectionEvents(event.Events):
         * exception re-writing
         * Establishing or disabling whether a connection or the owning
           connection pool is invalidated or expired in response to a
-          specific exception.
+          specific exception. [1]_.
 
         The hook is called while the cursor from the failed operation
         (if any) is still open and accessible.   Special cleanup operations
@@ -854,21 +854,17 @@ class ConnectionEvents(event.Events):
         the scope of this hook; the rollback of the per-statement transaction
         also occurs after the hook is called.
 
-        For the common case of detecting a "disconnect" situation which
-        is not currently handled by the SQLAlchemy dialect, the
-        :attr:`.ExceptionContext.is_disconnect` flag can be set to True which
-        will cause the exception to be considered as a disconnect situation,
-        which typically results in the connection pool being invalidated::
-
-            @event.listens_for(Engine, "handle_error")
-            def handle_exception(context):
-                if isinstance(context.original_exception, pyodbc.Error):
-                    for code in (
-                        '08S01', '01002', '08003',
-                        '08007', '08S02', '08001', 'HYT00', 'HY010'):
-
-                        if code in str(context.original_exception):
-                            context.is_disconnect = True
+        .. note::
+
+            .. [1] The pool "pre_ping" handler enabled using the
+                :paramref:`_sa.create_engine.pool_pre_ping` parameter does
+                **not** consult this event before deciding if the "ping"
+                returned false, as opposed to receiving an unhandled error.
+                For this use case, the :ref:`legacy recipe based on
+                engine_connect() may be used
+                <pool_disconnects_pessimistic_custom>`.  A future API allow
+                more comprehensive customization of the "disconnect"
+                detection mechanism across all functions.
 
         A handler function has two options for replacing
         the SQLAlchemy-constructed exception into one that is user