docs on dispose

diff --git a/doc/build/dbengine.rst b/doc/build/dbengine.rst
index 246dc9f7faca2e4264cb8045be2f3d3fbf4028c5..b9234b8e6f4c72e20a26741c1691351188e3548f 100644 (file)
--- a/doc/build/dbengine.rst
+++ b/doc/build/dbengine.rst
@@ -3,7 +3,7 @@
 ================
 Database Engines
 ================
-The **Engine** is the starting point for any SQLAlchemy application.  It's "home base" for the actual database and its DBAPI, delivered to the SQLAlchemy application through a connection pool and a **Dialect**, which describes how to talk to a specific kind of database/DBAPI combination.
+The **Engine** is the starting point for any SQLAlchemy application.  It's "home base" for the actual database and its DBAPI, delivered to the SQLAlchemy application through a connection pool and a **Dialect**, which describes how to talk to a specific kind of database/DBAPI combination.   
 
 The general structure is this::
 
@@ -23,6 +23,8 @@ Creating an engine is just a matter of issuing a single call, :func:`create_engi
 
 The above engine invokes the ``postgresql`` dialect and a connection pool which references ``localhost:5432``.
 
+Note that the appropriate usage of :func:`create_engine()` is once per particular configuration, held globally for the lifetime of a single application process (not including child processes via ``fork()`` - these would require a new engine).   A single :class:`~sqlalchemy.engine.base.Engine` manages connections on behalf of the process and is intended to be called upon in a concurrent fashion.   Creating engines for each particular operation is not the intended usage.
+
 The engine can be used directly to issue SQL to the database.  The most generic way is to use connections, which you get via the ``connect()`` method::
 
     connection = engine.connect()

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index dea13e16cf9f7acc64a89808dfc80400a873fdca..e9d4f04713739e954c9c8873f2d6fc17b335e9ab 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1493,6 +1493,29 @@ class Engine(Connectable, log.Identified):
         return 'Engine(%s)' % str(self.url)
 
     def dispose(self):
+        """Dispose of the connection pool used by this :class:`Engine`.
+
+        A new connection pool is created immediately after the old one has
+        been disposed.   This new pool, like all SQLAlchemy connection pools,
+        does not make any actual connections to the database until one is 
+        first requested.   
+        
+        This method has two general use cases:
+        
+         * When a dropped connection is detected, it is assumed that all
+           connections held by the pool are potentially dropped, and 
+           the entire pool is replaced.
+           
+         * An application may want to use :meth:`dispose` within a test 
+           suite that is creating multiple engines.
+           
+        It is critical to note that :meth:`dispose` does **not** guarantee
+        that the application will release all open database connections - only
+        those connections that are checked into the pool are closed.   
+        Connections which remain checked out or have been detached from
+        the engine are not affected. 
+        
+        """
         self.pool.dispose()
         self.pool = self.pool.recreate()