- Added new engine event :meth:`.ConnectionEvents.engine_disposed`.

Called after the :meth:`.Engine.dispose` method is called.

4 files changed, 50 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 3a87a44a7..c725d9e4a 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -19,6 +19,12 @@
     :version: 1.0.5
 
     .. change::
+        :tags: feature, engine
+
+        Added new engine event :meth:`.ConnectionEvents.engine_disposed`.
+        Called after the :meth:`.Engine.dispose` method is called.
+
+    .. change::
         :tags: bug, postgresql, pypy
         :tickets: 3439
 
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 7ebe39bbf..59754a436 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1834,6 +1834,7 @@ class Engine(Connectable, log.Identified):
         """
         self.pool.dispose()
         self.pool = self.pool.recreate()
+        self.dispatch.engine_disposed(self)
 
     def _execute_default(self, default):
         with self.contextual_connect() as conn:
diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index b2d4b54a9..f439d554f 100644
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -882,6 +882,23 @@ class ConnectionEvents(event.Events):
 
         """
 
+    def engine_disposed(self, engine):
+        """Intercept when the :meth:`.Engine.dispose` method is called.
+
+        The :meth:`.Engine.dispose` method instructs the engine to
+        "dispose" of it's connection pool (e.g. :class:`.Pool`), and
+        replaces it with a new one.  Disposing of the old pool has the
+        effect that existing checked-in connections are closed.  The new
+        pool does not establish any new connections until it is first used.
+
+        This event can be used to indicate that resources related to the
+        :class:`.Engine` should also be cleaned up, keeping in mind that the
+        :class:`.Engine` can still be used for new requests in which case
+        it re-acquires connection resources.
+
+        .. versionadded:: 1.0.5
+
+        """
     def begin(self, conn):
         """Intercept begin() events.
 
diff --git a/test/engine/test_execute.py b/test/engine/test_execute.py
index 761ac102a..c7b524335 100644
--- a/test/engine/test_execute.py
+++ b/test/engine/test_execute.py
@@ -484,6 +484,32 @@ class ExecuteTest(fixtures.TestBase):
         eq_(canary, ["l1", "l2", "l3", "l1", "l2"])
 
     @testing.requires.ad_hoc_engines
+    def test_dispose_event(self):
+        canary = Mock()
+        eng = create_engine(testing.db.url)
+        event.listen(eng, "engine_disposed", canary)
+
+        conn = eng.connect()
+        conn.close()
+        eng.dispose()
+
+
+        conn = eng.connect()
+        conn.close()
+
+        eq_(
+            canary.mock_calls,
+            [call(eng)]
+        )
+
+        eng.dispose()
+
+        eq_(
+            canary.mock_calls,
+            [call(eng), call(eng)]
+        )
+
+    @testing.requires.ad_hoc_engines
     def test_autocommit_option_no_issue_first_connect(self):
         eng = create_engine(testing.db.url)
         eng.update_execution_options(autocommit=True)