From 28aa32a20d71d582257c5f3c1f0cccb4d7f0f85c Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 15 May 2010 16:12:14 -0400 Subject: [PATCH] docs on dispose --- doc/build/dbengine.rst | 4 +++- lib/sqlalchemy/engine/base.py | 23 +++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/build/dbengine.rst b/doc/build/dbengine.rst index 246dc9f7fa..b9234b8e6f 100644 --- 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 dea13e16cf..e9d4f04713 100644 --- 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() -- 2.47.2