# SQLAlchemy 0.4 Documentation

Multiple Pages | One Page
Version: 0.4.6 Last Updated: 05/14/08 14:36:43

### module sqlalchemy.pool

Connection pooling for DB-API connections.

Provides a number of connection pool implementations for a variety of usage scenarios and thread behavior requirements imposed by the application, DB-API or database itself.

Also provides a DB-API 2.0 connection proxying mechanism allowing regular DB-API connect() methods to be transparently managed by a SQLAlchemy connection pool.

### Module Functions

def as_interface(obj, cls=None, methods=None, required=None)

Ensure basic interface compliance for an instance or dict of callables.

Checks that `obj` implements public methods of `cls` or has members listed in `methods`. If `required` is not supplied, implementing at least one interface method is sufficient. Methods present on `obj` that are not in the interface are ignored.

If `obj` is a dict and `dict` does not meet the interface requirements, the keys of the dictionary are inspected. Keys present in `obj` that are not in the interface will raise TypeErrors.

Raises TypeError if `obj` does not meet the interface criteria.

In all passing cases, an object with callable members is returned. In the simple case, `obj` is returned as-is; if dict processing kicks in then an anonymous class is returned.

obj
  A type, instance, or dictionary of callables.
cls
  Optional, a type. All public methods of cls are considered the interface. An `obj` instance of cls will always pass, ignoring `required`..
methods
  Optional, a sequence of method names to consider as the interface.
required
  Optional, a sequence of mandatory implementations. If omitted, an `obj` that provides at least one interface method is considered sufficient. As a convenience, required may be a type, in which case all public methods of the type are required.

def clear_managers()

Remove all current DB-API 2.0 managers.

All pools and connections are disposed.

def manage(module, **params)

Return a proxy for a DB-API module that automatically pools connections.

Given a DB-API 2.0 module and pool management parameters, returns a proxy for the module that will automatically pool connections, creating new connection pools for each distinct set of connection arguments sent to the decorated module's connect() function.

Arguments:

module
  A DB-API 2.0 database module.
poolclass
  The class used by the pool module to provide pooling. Defaults to `QueuePool`.

See the `Pool` class for options.

### class AssertionPool(Pool)

A Pool that allows at most one checked out connection at any given time.

This will raise an exception if more than one connection is checked out at a time. Useful for debugging code that is using more connections than desired.

def __init__(self, creator, **params)

Construct a new `AssertionPool`.

def create_connection(self)
def do_get(self)
def do_return_conn(self, conn)
def do_return_invalid(self, conn)
def status(self)
back to section top

### class NullPool(Pool)

A Pool which does not pool connections.

Instead it literally opens and closes the underlying DB-API connection per each connection open/close.

def do_get(self)
def do_return_conn(self, conn)
def do_return_invalid(self, conn)
def status(self)
back to section top

### class Pool(object)

Base class for connection pools.

This is an abstract class, implemented by various subclasses including:

QueuePool
  Pools multiple connections using `Queue.Queue`.
SingletonThreadPool
  Stores a single connection per execution thread.
NullPool
  Doesn't do any pooling; opens and closes connections.
AssertionPool
  Stores only one connection, and asserts that only one connection is checked out at a time.

The main argument, creator, is a callable function that returns a newly connected DB-API connection object.

Options that are understood by Pool are:

echo
  If set to True, connections being pulled and retrieved from/to the pool will be logged to the standard output, as well as pool sizing information. Echoing can also be achieved by enabling logging for the "sqlalchemy.pool" namespace. Defaults to False.
use_threadlocal
  If set to True, repeated calls to `connect()` within the same application thread will be guaranteed to return the same connection object, if one has already been retrieved from the pool and has not been returned yet. This allows code to retrieve a connection from the pool, and then while still holding on to that connection, to call other functions which also ask the pool for a connection of the same arguments; those functions will act upon the same connection that the calling method is using. Defaults to True.
recycle
  If set to non -1, a number of seconds between connection recycling, which means upon checkout, if this timeout is surpassed the connection will be closed and replaced with a newly opened connection. Defaults to -1.
listeners
  A list of `PoolListener`-like objects or dictionaries of callables that receive events when DB-API connections are created, checked out and checked in to the pool.
reset_on_return
  Defaults to True. Reset the database state of connections returned to the pool. This is typically a ROLLBACK to release locks and transaction resources. Disable at your own peril.

def __init__(self, creator, recycle=-1, echo=None, use_threadlocal=True, reset_on_return=True, listeners=None)

Construct a new `Pool`.

def add_listener(self, listener)

Add a `PoolListener`-like object to this pool.

`listener` may be an object that implements some or all of PoolListener, or a dictionary of callables containing implementations of some or all of the named methods in PoolListener.

def connect(self)
def create_connection(self)
def dispose(self)

Dispose of this pool.

This method leaves the possibility of checked-out connections remaining open, It is advised to not reuse the pool once dispose() is called, and to instead use a new pool constructed by the recreate() method.

def do_get(self)
def do_return_conn(self, conn)
def get(self)
def log(self, msg)
def recreate(self)

Return a new instance with identical creation arguments.

def return_conn(self, record)
def status(self)
def unique_connection(self)
back to section top

### class QueuePool(Pool)

A Pool that imposes a limit on the number of open connections.

Arguments include all those used by the base Pool class, as well as:

pool_size
  The size of the pool to be maintained. This is the largest number of connections that will be kept persistently in the pool. Note that the pool begins with no connections; once this number of connections is requested, that number of connections will remain. Defaults to 5.
max_overflow
  The maximum overflow size of the pool. When the number of checked-out connections reaches the size set in pool_size, additional connections will be returned up to this limit. When those additional connections are returned to the pool, they are disconnected and discarded. It follows then that the total number of simultaneous connections the pool will allow is pool_size + max_overflow, and the total number of "sleeping" connections the pool will allow is pool_size. max_overflow can be set to -1 to indicate no overflow limit; no limit will be placed on the total number of concurrent connections. Defaults to 10.
timeout
  The number of seconds to wait before giving up on returning a connection. Defaults to 30.

def __init__(self, creator, pool_size=5, max_overflow=10, timeout=30, **params)

Construct a new `QueuePool`.

def checkedin(self)
def checkedout(self)
def dispose(self)
def do_get(self)
def do_return_conn(self, conn)
def overflow(self)
def recreate(self)
def size(self)
def status(self)
back to section top

### class SingletonThreadPool(Pool)

A Pool that maintains one connection per thread.

Maintains one connection per each thread, never moving a connection to a thread other than the one which it was created in.

This is used for SQLite, which both does not handle multithreading by default, and also requires a singleton connection if a :memory: database is being used.

Options are the same as those of Pool, as well as:

pool_size: 5
  The number of threads in which to maintain connections at once.

def __init__(self, creator, pool_size=5, **params)

Construct a new `SingletonThreadPool`.

def cleanup(self)
def dispose(self)

Dispose of this pool.

this method leaves the possibility of checked-out connections remaining opened, so it is advised to not reuse the pool once dispose() is called, and to instead use a new pool constructed by the recreate() method.

def dispose_local(self)
def do_get(self)
def do_return_conn(self, conn)
def recreate(self)
def status(self)
back to section top

### class StaticPool(Pool)

A Pool of exactly one connection, used for all requests.

def __init__(self, creator, **params)

Construct a new `StaticPool`.

def create_connection(self)
def dispose(self)
def do_get(self)
def do_return_conn(self, conn)
def do_return_invalid(self, conn)
def status(self)
back to section top