SqlAlchemy 2.0 中文文档（四十六）（3）https://developer.aliyun.com/article/1563036
连接池事件
| 对象名称 | 描述 |
| PoolEvents | Pool的可用事件。 |
| PoolResetState | 描述了一个 DBAPI 连接在传递给PoolEvents.reset()连接池事件时的状态。 |
class sqlalchemy.events.PoolEvents
Pool的可用事件。
这里的方法定义了一个事件的名称以及传递给监听器函数的成员的名称。
例如：
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)
除了接受 Pool 类和 Pool 实例外，PoolEvents 还接受 Engine 对象和 Engine 类作为目标，这将解析为给定引擎的 .pool 属性或 Pool 类：
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") # will associate with engine.pool event.listen(engine, 'checkout', my_on_checkout)
成员
checkin(), checkout(), close(), close_detached(), connect(), detach(), dispatch, first_connect(), invalidate(), reset(), soft_invalidate()
类签名
class sqlalchemy.events.PoolEvents (sqlalchemy.event.Events)
method checkin(dbapi_connection: DBAPIConnection | None, connection_record: ConnectionPoolEntry) → None
当连接返回到池中时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'checkin') def receive_checkin(dbapi_connection, connection_record): "listen for the 'checkin' event" # ... (event handling logic) ...
注意连接可能会关闭，并且如果连接已失效，则可能为 None。对于已分离的连接，不会调用 checkin。（它们不会返回到池中。）
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method checkout(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, connection_proxy: PoolProxiedConnection) → None
当从池中检索到连接时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'checkout') def receive_checkout(dbapi_connection, connection_record, connection_proxy): "listen for the 'checkout' event" # ... (event handling logic) ...
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。connection_proxy–PoolProxiedConnection对象，它将在检出的生命周期内代理 DBAPI 连接的公共接口。
如果引发DisconnectionError，当前连接将被释放并重新获取新连接。所有检出监听器的处理将中止，并使用新连接重新启动。
另请参阅
ConnectionEvents.engine_connect() - 在创建新的Connection时发生的类似事件。
method close(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
当 DBAPI 连接关闭时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'close') def receive_close(dbapi_connection, connection_record): "listen for the 'close' event" # ... (event handling logic) ...
事件在关闭发生之前发出。
连接关闭可能会失败；通常是因为连接已经关闭。如果关闭操作失败，则连接将被丢弃。
close() 事件对应于仍与池相关联的连接。要拦截分离连接的关闭事件，请使用close_detached()。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method close_detached(dbapi_connection: DBAPIConnection) → None
当分离的 DBAPI 连接关闭时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'close_detached') def receive_close_detached(dbapi_connection): "listen for the 'close_detached' event" # ... (event handling logic) ...
事件在关闭发生之前发出。
连接关闭可能会失败；通常是因为连接已经关闭。如果关闭操作失败，则连接将被丢弃。
参数：
dbapi_connection – 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection 属性。
method connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
在为给定的Pool首次创建特定的 DBAPI 连接时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'connect') def receive_connect(dbapi_connection, connection_record): "listen for the 'connect' event" # ... (event handling logic) ...
此事件允许捕获直接在使用 DBAPI 模块级别的.connect()方法以产生新的 DBAPI 连接之后的点。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method detach(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
当 DBAPI 连接与池“分离”时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'detach') def receive_detach(dbapi_connection, connection_record): "listen for the 'detach' event" # ... (event handling logic) ...
此事件在分离后发生。连接不再与给定的连接记录关联。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
attribute dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.PoolEventsDispatch object>
回溯到 _Dispatch 类。
与 _Dispatch._events 双向对应
method first_connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
第一次从特定Pool检出 DBAPI 连接时仅调用一次此事件。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'first_connect') def receive_first_connect(dbapi_connection, connection_record): "listen for the 'first_connect' event" # ... (event handling logic) ...
PoolEvents.first_connect() 的原因是基于所有连接使用的设置来确定关于特定一系列数据库连接的信息。由于特定 Pool 指的是单个“创建者”函数（在 Engine 方面指的是使用的 URL 和连接选项），因此通常可以对单个连接进行观察，可以安全地假定关于所有后续连接都有效，例如数据库版本、服务器和客户端编码设置、排序设置等。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None
当 DBAPI 连接被“失效”时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'invalidate') def receive_invalidate(dbapi_connection, connection_record, exception): "listen for the 'invalidate' event" # ... (event handling logic) ...
每次调用 ConnectionPoolEntry.invalidate() 方法时都会触发此事件，无论是通过 API 使用还是通过“自动失效”触发，不带 soft 标志。
在最终尝试调用连接的.close()之前发生此事件。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。exception– 这次失效的原因对应的异常对象，如果有的话。可能为None。
另请参阅
更多关于失效的信息
method reset(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, reset_state: PoolResetState) → None
在池化连接发生“重置”操作之前调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'reset') def receive_reset(dbapi_connection, connection_record, reset_state): "listen for the 'reset' event" # ... (event handling logic) ... # DEPRECATED calling style (pre-2.0, will be removed in a future release) @event.listens_for(SomeEngineOrPool, 'reset') def receive_reset(dbapi_connection, connection_record): "listen for the 'reset' event" # ... (event handling logic) ...
从 2.0 版本开始更改：PoolEvents.reset() 事件现在接受参数 PoolEvents.reset.dbapi_connection、PoolEvents.reset.connection_record、PoolEvents.reset.reset_state。将在将来的版本中删除接受上述“已弃用”先前参数签名的侦听器函数的支持。
此事件表示在 DBAPI 连接上调用 rollback() 方法之前返回到池中或丢弃时发生。可以使用此事件钩子实现自定义“重置”策略，也可以通过使用 Pool.reset_on_return 参数禁用默认的“重置”行为。
PoolEvents.reset() 和 PoolEvents.checkin() 事件的主要区别在于 PoolEvents.reset() 不仅适用于被返回到池中的池化连接，还适用于使用 Connection.detach() 方法分离的连接以及由于在连接被检入之前进行垃圾回收而被丢弃的 asyncio 连接。
注意，并非所有使用 Connection.invalidate() 使连接无效的事件都会被触发。这些事件可以通过 PoolEvents.soft_invalidate() 和 PoolEvents.invalidate() 事件钩子拦截，所有的“连接关闭”事件都可以通过 PoolEvents.close() 拦截。
PoolEvents.reset() 事件通常在 PoolEvents.checkin() 事件之后发生，除了那些在重置后立即丢弃连接的情况。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。reset_state–PoolResetState实例，提供关于正在重置连接的情况的信息。
新版本为 2.0。
另请参阅
返回时重置
ConnectionEvents.rollback()
ConnectionEvents.commit()
method soft_invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None
当 DBAPI 连接要“软无效化”时调用。
示例参数形式：
from sqlalchemy import event @event.listens_for(SomeEngineOrPool, 'soft_invalidate') def receive_soft_invalidate(dbapi_connection, connection_record, exception): "listen for the 'soft_invalidate' event" # ... (event handling logic) ...
每当调用ConnectionPoolEntry.invalidate()方法时，都会发生此事件，带有soft标志。
软无效化指的是在当前连接被检入后，跟踪此连接的连接记录将强制重新连接。在调用时，它不会主动关闭 dbapi_connection。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。exception– 如果有原因导致无效化，则对应此无效化的异常对象。可能为None。
class sqlalchemy.events.PoolResetState
描述了 DBAPI 连接在传递给PoolEvents.reset()连接池事件时的状态。
成员
asyncio_safe，terminate_only，transaction_was_reset
新版本为 2.0.0b3。
attribute asyncio_safe: bool
指示重置操作是否发生在期望存在封闭事件循环的范围内的情况下，用于 asyncio 应用程序。
在连接被垃圾收集时，将为 False。
attribute terminate_only: bool
指示连接是否立即终止并且不被检入到池中。
这发生在无效的连接上，以及未被调用代码清理处理而被垃圾收集的 asyncio 连接上。在后一种情况下，在垃圾收集中无法安全地运行 asyncio 连接操作，因为不一定存在事件循环。
attribute transaction_was_reset: bool
表示如果 DBAPI 连接上的事务已经被Connection对象“重置”。
如果Connection具有事务状态，并且该状态未使用Connection.rollback()或Connection.commit()方法关闭；相反，事务在Connection.close()方法中内联关闭，因此在达到此事件时保证不会存在。
SqlAlchemy 2.0 中文文档（四十六）（5）https://developer.aliyun.com/article/1563039
