- more edits, references #3461

(cherry picked from commit 7aa2100db3e6f768a280b4dfdb675d6709f94625)

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 43084d265285629bef5908924b6cd24b55ce6c58..abc509a6e6967921abd61a881befe3d557ac4e86 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -378,18 +378,26 @@ circumstances, there are open database connections present while the
 :class:`.Engine` object is still resident in memory.   When an :class:`.Engine`
 is garbage collected, its connection pool is no longer referred to by
 that :class:`.Engine`, and assuming none of its connections are still checked
-out, the pool and its connections will also be checked in, which has the
-effect of closing out the actual database connections as well.
-
-The :class:`.Engine` is intended to normally be a long lived, typically permanent
-fixture throughout the lifespan of an application.  It is **not** intended
-to be created and disposed on a per-connection basis; it is instead
-a registry of connections.    However,  in those cases where it is desirable
-that all connection resources
-referred to by the :class:`.Engine` need to be completely closed out,
-the :class:`.Engine` can be explicitly disposed using the :meth:`.Engine.dispose`
-method.   This disposes of the engine's underlying connection pool and
-replaces it with a new one that's empty.   Provided that the :class:`.Engine`
+out, the pool and its connections will also be garbage collected, which has the
+effect of closing out the actual database connections as well.   But otherwise,
+the :class:`.Engine` will hold onto open database connections assuming
+it uses the normally default pool implementation of :class:`.QueuePool`.
+
+The :class:`.Engine` is intended to normally be a permanent
+fixture established up-front and maintained throughout the lifespan of an
+application.  It is **not** intended to be created and disposed on a
+per-connection basis; it is instead a registry that maintains both a pool
+of connections as well as configurational information about the database
+and DBAPI in use, as well as some degree of internal caching of per-database
+resources.
+
+However, there are many cases where it is desirable that all connection resources
+referred to by the :class:`.Engine` be completely closed out.  It's
+generally not a good idea to rely on Python garbage collection for this
+to occur for these cases; instead, the :class:`.Engine` can be explicitly disposed using
+the :meth:`.Engine.dispose` method.   This disposes of the engine's
+underlying connection pool and replaces it with a new one that's empty.
+Provided that the :class:`.Engine`
 is discarded at this point and no longer used, all **checked-in** connections
 which it refers to will also be fully closed.
 
@@ -414,11 +422,12 @@ engine is disposed or garbage collected, as these connections are still
 strongly referenced elsewhere by the application.
 However, after :meth:`.Engine.dispose` is called, those
 connections are no longer associated with that :class:`.Engine`; when they
-are closed, they will be returned to their now-orphned connection pool
-which will ultimately be garbage collected, once all connections are checked in.
-Since this process is not as clean, it is strongly recommended that
+are closed, they will be returned to their now-orphaned connection pool
+which will ultimately be garbage collected, once all connections which refer
+to it are also no longer referenced anywhere.
+Since this process is not easy to control, it is strongly recommended that
 :meth:`.Engine.dispose` is called only after all checked out connections
-are fully checked in.
+are checked in or otherwise de-associated from their pool.
 
 An alternative for applications that are negatively impacted by the
 :class:`.Engine` object's use of connection pooling is to disable pooling

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 847a68e0c7d3b039f24fe9cda9958247e01737fd..1ec6e16412cbcd31f0200688973ed8689cea91a8 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1689,8 +1689,10 @@ class Engine(Connectable, log.Identified):
         This has the effect of fully closing all **currently checked in**
         database connections.  Connections that are still checked out
         will **not** be closed, however they will no longer be associated
-        with this :class:`.Engine`, so when they are closed individually
-        they will close out fully.
+        with this :class:`.Engine`, so when they are closed individually,
+        eventually the :class:`.Pool` which they are associated with will
+        be garbage collected and they will be closed out fully, if
+        not already closed on checkin.
 
         A new connection pool is created immediately after the old one has
         been disposed.   This new pool, like all SQLAlchemy connection pools,