Release: 1.4.0b1 | Release Date: unreleased

SQLAlchemy 1.4 Documentation

不推荐使用的事件接口

本节描述了SQLAlchemy 0.5中引入的基于类的核心事件接口。ORM模拟在 已弃用的ORM事件接口 .

0.7 版后已移除: 中描述的新事件系统 事件 替换扩展/代理/侦听器系统,为所有事件提供一致的接口,而不需要子类化。

执行、连接和光标事件

class sqlalchemy.interfaces.ConnectionProxy

允许通过连接拦截语句执行。

0.7 版后已移除: ConnectionProxy 已弃用,将在将来的版本中删除。请参考 event.listen()ConnectionEvents 侦听器接口。

或者两者都是 execute()cursor_execute() 可实现截获编译语句和光标级执行,例如:

class MyProxy(ConnectionProxy):
    def execute(self, conn, execute, clauseelement,
                *multiparams, **params):
        print "compiled statement:", clauseelement
        return execute(clauseelement, *multiparams, **params)

    def cursor_execute(self, execute, cursor, statement,
                       parameters, context, executemany):
        print "raw statement:", statement
        return execute(cursor, statement, parameters, context)

这个 execute 参数是一个函数,它将实现操作的默认执行行为。应使用示例中所示的签名。

代理已安装到 Engine 通过 proxy 论点:

e = create_engine('someurl://', proxy=MyProxy())
begin(conn, begin)

intercept begin()事件。

begin_twophase(conn, begin_twophase, xid)

intercept开始执行twophase()事件。

commit(conn, commit)

intercept commit()事件。

commit_twophase(conn, commit_twophase, xid, is_prepared)

intercept commit&twophase()事件。

cursor_execute(execute, cursor, statement, parameters, context, executemany)

拦截低级游标execute()事件。

execute(conn, execute, clauseelement, *multiparams, **params)

拦截高级execute()事件。

prepare_twophase(conn, prepare_twophase, xid)

拦截准备阶段()事件。

release_savepoint(conn, release_savepoint, name, context)

拦截释放_savepoint()事件。

rollback(conn, rollback)

intercept rollback()事件。

rollback_savepoint(conn, rollback_savepoint, name, context)

截获回滚保存点()事件。

rollback_twophase(conn, rollback_twophase, xid, is_prepared)

intercept rollback兘thophase()事件。

savepoint(conn, savepoint, name=None)

拦截savepoint()事件。

连接池事件

class sqlalchemy.interfaces.PoolListener

连接到连接的生命周期 Pool .

0.7 版后已移除: PoolListener 已弃用,将在将来的版本中删除。请参考 event.listen()PoolEvents 侦听器接口。

用法:

class MyListener(PoolListener):
    def connect(self, dbapi_con, con_record):
        '''perform connect operations'''
    # etc.

# create a new pool with a listener
p = QueuePool(..., listeners=[MyListener()])

# add a listener after the fact
p.add_listener(MyListener())

# usage with create_engine()
e = create_engine("url://", listeners=[MyListener()])

所有标准连接 Pool 类型可以接受关键连接生命周期事件的事件侦听器:创建、池签出和签入。连接关闭时不触发任何事件。

对于任何给定的DB-API连接,都将有一个 connect 事件, ncheckout 事件,以及 nn - 1 checkin 事件。(如果A Connection 通过 detach() 方法,它将不会被签回。)

这些是低级对象的低级事件:原始的python db-api连接,没有sqlAlchemy的便利性 Connection 包装器, Dialect 服务或 ClauseElement 执行。如果通过连接执行SQL,建议显式关闭所有游标和其他资源。

事件还接收到 _ConnectionRecord ,一个长寿的内部 Pool 对象,它基本上表示连接池中的“插槽”。 _ConnectionRecord 对象有一个公共的注意属性: info ,其内容范围为由记录管理的db-api连接的生存期的字典。您可以随意使用这个共享存储区域。

不需要子类 PoolListener 处理事件。实现一个或多个这些方法的任何类都可以用作池侦听器。这个 Pool 将检查侦听器对象提供的方法,并根据其功能将侦听器添加到一个或多个内部事件队列中。在效率和函数调用开销方面,只为将要使用的钩子提供实现会更好。

checkin(dbapi_con, con_record)

当连接返回池时调用。

请注意,连接可能已关闭,如果连接已失效,则可能为“无”。 checkin 不会为分离的连接调用。(他们不回池。)

dbapi_con

原始DB-API连接

con_record

这个 _ConnectionRecord 持续管理连接

checkout(dbapi_con, con_record, con_proxy)

从池中检索连接时调用。

dbapi_con

原始DB-API连接

con_record

这个 _ConnectionRecord 持续管理连接

con_proxy

这个 _ConnectionFairy 它管理当前签出范围的连接。

如果你举起 exc.DisconnectionError ,将释放当前连接并检索新连接。所有签出侦听器的处理将中止并使用新连接重新启动。

connect(dbapi_con, con_record)

为每个新的DB-API连接或池调用一次 creator() .

dbapi_con

新连接的原始DB-API连接(不是SQLAlchemy Connection 包装器)。

con_record

这个 _ConnectionRecord 持续管理连接

first_connect(dbapi_con, con_record)

对第一个DB-API连接精确调用一次。

dbapi_con

新连接的原始DB-API连接(不是SQLAlchemy Connection 包装器)。

con_record

这个 _ConnectionRecord 持续管理连接

Previous: 运行时检查API Next: 核心异常