sqlalchemy.engine.events.ConnectionEvents

Intercept low-level cursor execute() events before execution, receiving the string SQL statement and DBAPI-specific parameter list to be invoked against a cursor.

This event is a good choice for logging as well as late modifications to the SQL string. It's less ideal for parameter modifications except for those which are specific to a target backend.

This event can be optionally established with the retval=True flag. The statement and parameters arguments should be returned as a two-tuple in this case:

@event.listens_for(Engine, "before_cursor_execute", retval=True)
def before_cursor_execute(conn, cursor, statement,
                parameters, context, executemany):
    # do something with statement, parameters
    return statement, parameters

See the example at _events.ConnectionEvents.

Intercept high level execute() events, receiving uncompiled SQL constructs and other objects prior to rendering into SQL.

This event is good for debugging SQL compilation issues as well as early manipulation of the parameters being sent to the database, as the parameter lists will be in a consistent format here.

This event can be optionally established with the retval=True flag. The clauseelement, multiparams, and params arguments should be returned as a three-tuple in this case:

@event.listens_for(Engine, "before_execute", retval=True)
def before_execute(conn, clauseelement, multiparams, params):
    # do something with clauseelement, multiparams, params
    return clauseelement, multiparams, params

Intercept commit() events, as initiated by a .Transaction.

Note that the _pool.Pool may also "auto-commit" a DBAPI connection upon checkin, if the reset_on_return flag is set to the value 'commit'. To intercept this commit, use the _events.PoolEvents.reset hook.

Intercept the creation of a new _engine.Connection.

This event is called typically as the direct result of calling the _engine.Engine.connect method.

It differs from the _events.PoolEvents.connect method, which refers to the actual connection to a database at the DBAPI level; a DBAPI connection may be pooled and reused for many operations. In contrast, this event refers only to the production of a higher level _engine.Connection wrapper around such a DBAPI connection.

It also differs from the _events.PoolEvents.checkout event in that it is specific to the _engine.Connection object, not the DBAPI connection that _events.PoolEvents.checkout deals with, although this DBAPI connection is available here via the _engine.Connection.connection attribute. But note there can in fact be multiple _events.PoolEvents.checkout events within the lifespan of a single _engine.Connection object, if that _engine.Connection is invalidated and re-established. There can also be multiple _engine.Connection objects generated for the same already-checked-out DBAPI connection, in the case that a "branch" of a _engine.Connection is produced.

Intercept when the _engine.Engine.dispose method is called.

The _engine.Engine.dispose method instructs the engine to "dispose" of it's connection pool (e.g. _pool.Pool), and replaces it with a new one. Disposing of the old pool has the effect that existing checked-in connections are closed. The new pool does not establish any new connections until it is first used.

This event can be used to indicate that resources related to the _engine.Engine should also be cleaned up, keeping in mind that the _engine.Engine can still be used for new requests in which case it re-acquires connection resources.

Intercept all exceptions processed by the _engine.Connection.

This includes all exceptions emitted by the DBAPI as well as within SQLAlchemy's statement invocation process, including encoding errors and other statement validation errors. Other areas in which the event is invoked include transaction begin and end, result row fetching, cursor creation.

Note that .handle_error may support new kinds of exceptions and new calling scenarios at any time. Code which uses this event must expect new calling patterns to be present in minor releases.

To support the wide variety of members that correspond to an exception, as well as to allow extensibility of the event without backwards incompatibility, the sole argument received is an instance of .ExceptionContext. This object contains data members representing detail about the exception.

Use cases supported by this hook include:

• read-only, low-level exception handling for logging and debugging purposes
• exception re-writing
• Establishing or disabling whether a connection or the owning connection pool is invalidated or expired in response to a specific exception [1].

The hook is called while the cursor from the failed operation (if any) is still open and accessible. Special cleanup operations can be called on this cursor; SQLAlchemy will attempt to close this cursor subsequent to this hook being invoked. If the connection is in "autocommit" mode, the transaction also remains open within the scope of this hook; the rollback of the per-statement transaction also occurs after the hook is called.

A handler function has two options for replacing the SQLAlchemy-constructed exception into one that is user defined. It can either raise this new exception directly, in which case all further event listeners are bypassed and the exception will be raised, after appropriate cleanup as taken place:

@event.listens_for(Engine, "handle_error")
def handle_exception(context):
    if isinstance(context.original_exception,
        psycopg2.OperationalError) and \
        "failed" in str(context.original_exception):
        raise MySpecialException("failed operation")

Alternatively, a "chained" style of event handling can be used, by configuring the handler with the retval=True modifier and returning the new exception instance from the function. In this case, event handling will continue onto the next handler. The "chained" exception is available using .ExceptionContext.chained_exception:

@event.listens_for(Engine, "handle_error", retval=True)
def handle_exception(context):
    if context.chained_exception is not None and \
        "special" in context.chained_exception.message:
        return MySpecialException("failed",
            cause=context.chained_exception)

Handlers that return None may be used within the chain; when a handler returns None, the previous exception instance, if any, is maintained as the current exception that is passed onto the next handler.

When a custom exception is raised or returned, SQLAlchemy raises this new exception as-is, it is not wrapped by any SQLAlchemy object. If the exception is not a subclass of sqlalchemy.exc.StatementError, certain features may not be available; currently this includes the ORM's feature of adding a detail hint about "autoflush" to exceptions raised within the autoflush process.

Intercept rollback() events, as initiated by a .Transaction.

Note that the _pool.Pool also "auto-rolls back" a DBAPI connection upon checkin, if the reset_on_return flag is set to its default value of 'rollback'. To intercept this rollback, use the _events.PoolEvents.reset hook.

Intercept when the _engine.Connection.execution_options method is called.

This method is called after the new _engine.Connection has been produced, with the newly updated execution options collection, but before the .Dialect has acted upon any of those new options.

Note that this method is not called when a new _engine.Connection is produced which is inheriting execution options from its parent _engine.Engine; to intercept this condition, use the _events.ConnectionEvents.engine_connect event.

Intercept when the _engine.Engine.execution_options method is called.

The _engine.Engine.execution_options method produces a shallow copy of the _engine.Engine which stores the new options. That new _engine.Engine is passed here. A particular application of this method is to add a _events.ConnectionEvents.engine_connect event handler to the given _engine.Engine which will perform some per- _engine.Connection task specific to these execution options.