Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# pool/events.py
2# Copyright (C) 2005-2024 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7from __future__ import annotations
9import typing
10from typing import Any
11from typing import Optional
12from typing import Type
13from typing import Union
15from .base import ConnectionPoolEntry
16from .base import Pool
17from .base import PoolProxiedConnection
18from .base import PoolResetState
19from .. import event
20from .. import util
22if typing.TYPE_CHECKING:
23 from ..engine import Engine
24 from ..engine.interfaces import DBAPIConnection
27class PoolEvents(event.Events[Pool]):
28 """Available events for :class:`_pool.Pool`.
30 The methods here define the name of an event as well
31 as the names of members that are passed to listener
32 functions.
34 e.g.::
36 from sqlalchemy import event
38 def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
39 "handle an on checkout event"
41 event.listen(Pool, 'checkout', my_on_checkout)
43 In addition to accepting the :class:`_pool.Pool` class and
44 :class:`_pool.Pool` instances, :class:`_events.PoolEvents` also accepts
45 :class:`_engine.Engine` objects and the :class:`_engine.Engine` class as
46 targets, which will be resolved to the ``.pool`` attribute of the
47 given engine or the :class:`_pool.Pool` class::
49 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
51 # will associate with engine.pool
52 event.listen(engine, 'checkout', my_on_checkout)
54 """ # noqa: E501
56 _target_class_doc = "SomeEngineOrPool"
57 _dispatch_target = Pool
59 @util.preload_module("sqlalchemy.engine")
60 @classmethod
61 def _accept_with(
62 cls,
63 target: Union[Pool, Type[Pool], Engine, Type[Engine]],
64 identifier: str,
65 ) -> Optional[Union[Pool, Type[Pool]]]:
66 if not typing.TYPE_CHECKING:
67 Engine = util.preloaded.engine.Engine
69 if isinstance(target, type):
70 if issubclass(target, Engine):
71 return Pool
72 else:
73 assert issubclass(target, Pool)
74 return target
75 elif isinstance(target, Engine):
76 return target.pool
77 elif isinstance(target, Pool):
78 return target
79 elif hasattr(target, "_no_async_engine_events"):
80 target._no_async_engine_events()
81 else:
82 return None
84 @classmethod
85 def _listen(
86 cls,
87 event_key: event._EventKey[Pool],
88 **kw: Any,
89 ) -> None:
90 target = event_key.dispatch_target
92 kw.setdefault("asyncio", target._is_asyncio)
94 event_key.base_listen(**kw)
96 def connect(
97 self,
98 dbapi_connection: DBAPIConnection,
99 connection_record: ConnectionPoolEntry,
100 ) -> None:
101 """Called at the moment a particular DBAPI connection is first
102 created for a given :class:`_pool.Pool`.
104 This event allows one to capture the point directly after which
105 the DBAPI module-level ``.connect()`` method has been used in order
106 to produce a new DBAPI connection.
108 :param dbapi_connection: a DBAPI connection.
109 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
111 :param connection_record: the :class:`.ConnectionPoolEntry` managing
112 the DBAPI connection.
114 """
116 def first_connect(
117 self,
118 dbapi_connection: DBAPIConnection,
119 connection_record: ConnectionPoolEntry,
120 ) -> None:
121 """Called exactly once for the first time a DBAPI connection is
122 checked out from a particular :class:`_pool.Pool`.
124 The rationale for :meth:`_events.PoolEvents.first_connect`
125 is to determine
126 information about a particular series of database connections based
127 on the settings used for all connections. Since a particular
128 :class:`_pool.Pool`
129 refers to a single "creator" function (which in terms
130 of a :class:`_engine.Engine`
131 refers to the URL and connection options used),
132 it is typically valid to make observations about a single connection
133 that can be safely assumed to be valid about all subsequent
134 connections, such as the database version, the server and client
135 encoding settings, collation settings, and many others.
137 :param dbapi_connection: a DBAPI connection.
138 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
140 :param connection_record: the :class:`.ConnectionPoolEntry` managing
141 the DBAPI connection.
143 """
145 def checkout(
146 self,
147 dbapi_connection: DBAPIConnection,
148 connection_record: ConnectionPoolEntry,
149 connection_proxy: PoolProxiedConnection,
150 ) -> None:
151 """Called when a connection is retrieved from the Pool.
153 :param dbapi_connection: a DBAPI connection.
154 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
156 :param connection_record: the :class:`.ConnectionPoolEntry` managing
157 the DBAPI connection.
159 :param connection_proxy: the :class:`.PoolProxiedConnection` object
160 which will proxy the public interface of the DBAPI connection for the
161 lifespan of the checkout.
163 If you raise a :class:`~sqlalchemy.exc.DisconnectionError`, the current
164 connection will be disposed and a fresh connection retrieved.
165 Processing of all checkout listeners will abort and restart
166 using the new connection.
168 .. seealso:: :meth:`_events.ConnectionEvents.engine_connect`
169 - a similar event
170 which occurs upon creation of a new :class:`_engine.Connection`.
172 """
174 def checkin(
175 self,
176 dbapi_connection: Optional[DBAPIConnection],
177 connection_record: ConnectionPoolEntry,
178 ) -> None:
179 """Called when a connection returns to the pool.
181 Note that the connection may be closed, and may be None if the
182 connection has been invalidated. ``checkin`` will not be called
183 for detached connections. (They do not return to the pool.)
185 :param dbapi_connection: a DBAPI connection.
186 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
188 :param connection_record: the :class:`.ConnectionPoolEntry` managing
189 the DBAPI connection.
191 """
193 @event._legacy_signature(
194 "2.0",
195 ["dbapi_connection", "connection_record"],
196 lambda dbapi_connection, connection_record, reset_state: (
197 dbapi_connection,
198 connection_record,
199 ),
200 )
201 def reset(
202 self,
203 dbapi_connection: DBAPIConnection,
204 connection_record: ConnectionPoolEntry,
205 reset_state: PoolResetState,
206 ) -> None:
207 """Called before the "reset" action occurs for a pooled connection.
209 This event represents
210 when the ``rollback()`` method is called on the DBAPI connection
211 before it is returned to the pool or discarded.
212 A custom "reset" strategy may be implemented using this event hook,
213 which may also be combined with disabling the default "reset"
214 behavior using the :paramref:`_pool.Pool.reset_on_return` parameter.
216 The primary difference between the :meth:`_events.PoolEvents.reset` and
217 :meth:`_events.PoolEvents.checkin` events are that
218 :meth:`_events.PoolEvents.reset` is called not just for pooled
219 connections that are being returned to the pool, but also for
220 connections that were detached using the
221 :meth:`_engine.Connection.detach` method as well as asyncio connections
222 that are being discarded due to garbage collection taking place on
223 connections before the connection was checked in.
225 Note that the event **is not** invoked for connections that were
226 invalidated using :meth:`_engine.Connection.invalidate`. These
227 events may be intercepted using the :meth:`.PoolEvents.soft_invalidate`
228 and :meth:`.PoolEvents.invalidate` event hooks, and all "connection
229 close" events may be intercepted using :meth:`.PoolEvents.close`.
231 The :meth:`_events.PoolEvents.reset` event is usually followed by the
232 :meth:`_events.PoolEvents.checkin` event, except in those
233 cases where the connection is discarded immediately after reset.
235 :param dbapi_connection: a DBAPI connection.
236 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
238 :param connection_record: the :class:`.ConnectionPoolEntry` managing
239 the DBAPI connection.
241 :param reset_state: :class:`.PoolResetState` instance which provides
242 information about the circumstances under which the connection
243 is being reset.
245 .. versionadded:: 2.0
247 .. seealso::
249 :ref:`pool_reset_on_return`
251 :meth:`_events.ConnectionEvents.rollback`
253 :meth:`_events.ConnectionEvents.commit`
255 """
257 def invalidate(
258 self,
259 dbapi_connection: DBAPIConnection,
260 connection_record: ConnectionPoolEntry,
261 exception: Optional[BaseException],
262 ) -> None:
263 """Called when a DBAPI connection is to be "invalidated".
265 This event is called any time the
266 :meth:`.ConnectionPoolEntry.invalidate` method is invoked, either from
267 API usage or via "auto-invalidation", without the ``soft`` flag.
269 The event occurs before a final attempt to call ``.close()`` on the
270 connection occurs.
272 :param dbapi_connection: a DBAPI connection.
273 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
275 :param connection_record: the :class:`.ConnectionPoolEntry` managing
276 the DBAPI connection.
278 :param exception: the exception object corresponding to the reason
279 for this invalidation, if any. May be ``None``.
281 .. seealso::
283 :ref:`pool_connection_invalidation`
285 """
287 def soft_invalidate(
288 self,
289 dbapi_connection: DBAPIConnection,
290 connection_record: ConnectionPoolEntry,
291 exception: Optional[BaseException],
292 ) -> None:
293 """Called when a DBAPI connection is to be "soft invalidated".
295 This event is called any time the
296 :meth:`.ConnectionPoolEntry.invalidate`
297 method is invoked with the ``soft`` flag.
299 Soft invalidation refers to when the connection record that tracks
300 this connection will force a reconnect after the current connection
301 is checked in. It does not actively close the dbapi_connection
302 at the point at which it is called.
304 :param dbapi_connection: a DBAPI connection.
305 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
307 :param connection_record: the :class:`.ConnectionPoolEntry` managing
308 the DBAPI connection.
310 :param exception: the exception object corresponding to the reason
311 for this invalidation, if any. May be ``None``.
313 """
315 def close(
316 self,
317 dbapi_connection: DBAPIConnection,
318 connection_record: ConnectionPoolEntry,
319 ) -> None:
320 """Called when a DBAPI connection is closed.
322 The event is emitted before the close occurs.
324 The close of a connection can fail; typically this is because
325 the connection is already closed. If the close operation fails,
326 the connection is discarded.
328 The :meth:`.close` event corresponds to a connection that's still
329 associated with the pool. To intercept close events for detached
330 connections use :meth:`.close_detached`.
332 :param dbapi_connection: a DBAPI connection.
333 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
335 :param connection_record: the :class:`.ConnectionPoolEntry` managing
336 the DBAPI connection.
338 """
340 def detach(
341 self,
342 dbapi_connection: DBAPIConnection,
343 connection_record: ConnectionPoolEntry,
344 ) -> None:
345 """Called when a DBAPI connection is "detached" from a pool.
347 This event is emitted after the detach occurs. The connection
348 is no longer associated with the given connection record.
350 :param dbapi_connection: a DBAPI connection.
351 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
353 :param connection_record: the :class:`.ConnectionPoolEntry` managing
354 the DBAPI connection.
356 """
358 def close_detached(self, dbapi_connection: DBAPIConnection) -> None:
359 """Called when a detached DBAPI connection is closed.
361 The event is emitted before the close occurs.
363 The close of a connection can fail; typically this is because
364 the connection is already closed. If the close operation fails,
365 the connection is discarded.
367 :param dbapi_connection: a DBAPI connection.
368 The :attr:`.ConnectionPoolEntry.dbapi_connection` attribute.
370 """