sqlalchemy.pool.events.PoolEvents

class documentation

class PoolEvents(event.Events):

Available events for _pool.Pool.

The methods here define the name of an event as well as the names of members that are passed to listener functions.

e.g.:

from sqlalchemy import event

def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
    "handle an on checkout event"

event.listen(Pool, 'checkout', my_on_checkout)

In addition to accepting the _pool.Pool class and _pool.Pool instances, _events.PoolEvents also accepts _engine.Engine objects and the _engine.Engine class as targets, which will be resolved to the .pool attribute of the given engine or the _pool.Pool class:

engine = create_engine("postgresql://scott:tiger@localhost/test")

# will associate with engine.pool
event.listen(engine, 'checkout', my_on_checkout)

Class Method	`_accept_with`	Undocumented
Class Method	`_listen`	Undocumented
Method	`checkin`	Called when a connection returns to the pool.
Method	`checkout`	Called when a connection is retrieved from the Pool.
Method	`close`	Called when a DBAPI connection is closed.
Method	`close_detached`	Called when a detached DBAPI connection is closed.
Method	`connect`	Called at the moment a particular DBAPI connection is first created for a given `_pool.Pool`.
Method	`detach`	Called when a DBAPI connection is "detached" from a pool.
Method	`first_connect`	Called exactly once for the first time a DBAPI connection is checked out from a particular `_pool.Pool`.
Method	`invalidate`	Called when a DBAPI connection is to be "invalidated".
Method	`reset`	Called before the "reset" action occurs for a pooled connection.
Method	`soft_invalidate`	Called when a DBAPI connection is to be "soft invalidated".
Class Variable	`_target_class_doc`	Undocumented

Inherited from Events:

Class Method	`_clear`	Undocumented
Class Method	`_remove`	Undocumented
Static Method	`_set_dispatch`	Undocumented

@classmethod
def _accept_with(cls, target):

overrides sqlalchemy.event.base.Events._accept_with

Undocumented

@classmethod
def _listen(cls, event_key, **kw):

overrides sqlalchemy.event.base.Events._listen

Undocumented

def checkin(self, dbapi_connection, connection_record):

Called when a connection returns to the pool.

Note that the connection may be closed, and may be None if the connection has been invalidated. checkin will not be called for detached connections. (They do not return to the pool.)

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.

def checkout(self, dbapi_connection, connection_record, connection_proxy):

Called when a connection is retrieved from the Pool.

If you raise a ~sqlalchemy.exc.DisconnectionError, the current connection will be disposed and a fresh connection retrieved. Processing of all checkout listeners will abort and restart using the new connection.

See Also

_events.ConnectionEvents.engine_connect - a similar event which occurs upon creation of a new _engine.Connection.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.
connection_proxy	the `._ConnectionFairy` object which will proxy the public interface of the DBAPI connection for the lifespan of the checkout.

def close(self, dbapi_connection, connection_record):

Called when a DBAPI connection is closed.

The event is emitted before the close occurs.

The close of a connection can fail; typically this is because the connection is already closed. If the close operation fails, the connection is discarded.

The .close event corresponds to a connection that's still associated with the pool. To intercept close events for detached connections use .close_detached.

New in version 1.1.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.

def close_detached(self, dbapi_connection):

Called when a detached DBAPI connection is closed.

The event is emitted before the close occurs.

The close of a connection can fail; typically this is because the connection is already closed. If the close operation fails, the connection is discarded.

New in version 1.1.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.

def connect(self, dbapi_connection, connection_record):

Called at the moment a particular DBAPI connection is first created for a given _pool.Pool.

This event allows one to capture the point directly after which the DBAPI module-level .connect() method has been used in order to produce a new DBAPI connection.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.

def detach(self, dbapi_connection, connection_record):

Called when a DBAPI connection is "detached" from a pool.

This event is emitted after the detach occurs. The connection is no longer associated with the given connection record.

New in version 1.1.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.

def first_connect(self, dbapi_connection, connection_record):

Called exactly once for the first time a DBAPI connection is checked out from a particular _pool.Pool.

The rationale for _events.PoolEvents.first_connect is to determine information about a particular series of database connections based on the settings used for all connections. Since a particular _pool.Pool refers to a single "creator" function (which in terms of a _engine.Engine refers to the URL and connection options used), it is typically valid to make observations about a single connection that can be safely assumed to be valid about all subsequent connections, such as the database version, the server and client encoding settings, collation settings, and many others.

Parameters
dbapi_connection	a DBAPI connection. The `._ConnectionRecord.dbapi_connection` attribute.
connection_record	the `._ConnectionRecord` managing the DBAPI connection.

def invalidate(self, dbapi_connection, connection_record, exception):

Called when a DBAPI connection is to be "invalidated".

This event is called any time the ._ConnectionRecord.invalidate method is invoked, either from API usage or via "auto-invalidation", without the soft flag.

The event occurs before a final attempt to call .close() on the connection occurs.

New in version 0.9.2: Added support for connection invalidation listening.