date: Sat May 15 16:12:14 2010 -0400
docs on dispose
doc/build/dbengine.rst | 4 +++-
lib/sqlalchemy/engine/base.py | 23 +++++++++++++++++++++++
2 files changed, 26 insertions(+), 1 deletions(-)
diffs (54 lines):
diff -r 47ba31347a02 -r 483686478c6a doc/build/dbengine.rst
--- a/doc/build/dbengine.rst Sat May 15 15:56:49 2010 -0400
+++ b/doc/build/dbengine.rst Sat May 15 16:12:14 2010 -0400
@@ -3,7 +3,7 @@
-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 @@
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 -r 47ba31347a02 -r 483686478c6a lib/sqlalchemy/engine/base.py
--- a/lib/sqlalchemy/engine/base.py Sat May 15 15:56:49 2010 -0400
+++ b/lib/sqlalchemy/engine/base.py Sat May 15 16:12:14 2010 -0400
@@ -1493,6 +1493,29 @@
return 'Engine(%s)' % str(self.url)
+ """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 = self.pool.recreate()