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# engine/events.py
2# Copyright (C) 2005-2025 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
9from __future__ import annotations
11import typing
12from typing import Any
13from typing import Dict
14from typing import Optional
15from typing import Tuple
16from typing import Type
17from typing import Union
19from .base import Connection
20from .base import Engine
21from .interfaces import ConnectionEventsTarget
22from .interfaces import DBAPIConnection
23from .interfaces import DBAPICursor
24from .interfaces import Dialect
25from .. import event
26from .. import exc
27from ..util.typing import Literal
29if typing.TYPE_CHECKING:
30 from .interfaces import _CoreMultiExecuteParams
31 from .interfaces import _CoreSingleExecuteParams
32 from .interfaces import _DBAPIAnyExecuteParams
33 from .interfaces import _DBAPIMultiExecuteParams
34 from .interfaces import _DBAPISingleExecuteParams
35 from .interfaces import _ExecuteOptions
36 from .interfaces import ExceptionContext
37 from .interfaces import ExecutionContext
38 from .result import Result
39 from ..pool import ConnectionPoolEntry
40 from ..sql import Executable
41 from ..sql.elements import BindParameter
44class ConnectionEvents(event.Events[ConnectionEventsTarget]):
45 """Available events for
46 :class:`_engine.Connection` and :class:`_engine.Engine`.
48 The methods here define the name of an event as well as the names of
49 members that are passed to listener functions.
51 An event listener can be associated with any
52 :class:`_engine.Connection` or :class:`_engine.Engine`
53 class or instance, such as an :class:`_engine.Engine`, e.g.::
55 from sqlalchemy import event, create_engine
58 def before_cursor_execute(
59 conn, cursor, statement, parameters, context, executemany
60 ):
61 log.info("Received statement: %s", statement)
64 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
65 event.listen(engine, "before_cursor_execute", before_cursor_execute)
67 or with a specific :class:`_engine.Connection`::
69 with engine.begin() as conn:
71 @event.listens_for(conn, "before_cursor_execute")
72 def before_cursor_execute(
73 conn, cursor, statement, parameters, context, executemany
74 ):
75 log.info("Received statement: %s", statement)
77 When the methods are called with a `statement` parameter, such as in
78 :meth:`.after_cursor_execute` or :meth:`.before_cursor_execute`,
79 the statement is the exact SQL string that was prepared for transmission
80 to the DBAPI ``cursor`` in the connection's :class:`.Dialect`.
82 The :meth:`.before_execute` and :meth:`.before_cursor_execute`
83 events can also be established with the ``retval=True`` flag, which
84 allows modification of the statement and parameters to be sent
85 to the database. The :meth:`.before_cursor_execute` event is
86 particularly useful here to add ad-hoc string transformations, such
87 as comments, to all executions::
89 from sqlalchemy.engine import Engine
90 from sqlalchemy import event
93 @event.listens_for(Engine, "before_cursor_execute", retval=True)
94 def comment_sql_calls(
95 conn, cursor, statement, parameters, context, executemany
96 ):
97 statement = statement + " -- some comment"
98 return statement, parameters
100 .. note:: :class:`_events.ConnectionEvents` can be established on any
101 combination of :class:`_engine.Engine`, :class:`_engine.Connection`,
102 as well
103 as instances of each of those classes. Events across all
104 four scopes will fire off for a given instance of
105 :class:`_engine.Connection`. However, for performance reasons, the
106 :class:`_engine.Connection` object determines at instantiation time
107 whether or not its parent :class:`_engine.Engine` has event listeners
108 established. Event listeners added to the :class:`_engine.Engine`
109 class or to an instance of :class:`_engine.Engine`
110 *after* the instantiation
111 of a dependent :class:`_engine.Connection` instance will usually
112 *not* be available on that :class:`_engine.Connection` instance.
113 The newly
114 added listeners will instead take effect for
115 :class:`_engine.Connection`
116 instances created subsequent to those event listeners being
117 established on the parent :class:`_engine.Engine` class or instance.
119 :param retval=False: Applies to the :meth:`.before_execute` and
120 :meth:`.before_cursor_execute` events only. When True, the
121 user-defined event function must have a return value, which
122 is a tuple of parameters that replace the given statement
123 and parameters. See those methods for a description of
124 specific return arguments.
126 """ # noqa
128 _target_class_doc = "SomeEngine"
129 _dispatch_target = ConnectionEventsTarget
131 @classmethod
132 def _accept_with(
133 cls,
134 target: Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]],
135 identifier: str,
136 ) -> Optional[Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]]]:
137 default_dispatch = super()._accept_with(target, identifier)
138 if default_dispatch is None and hasattr(
139 target, "_no_async_engine_events"
140 ):
141 target._no_async_engine_events()
143 return default_dispatch
145 @classmethod
146 def _listen(
147 cls,
148 event_key: event._EventKey[ConnectionEventsTarget],
149 *,
150 retval: bool = False,
151 **kw: Any,
152 ) -> None:
153 target, identifier, fn = (
154 event_key.dispatch_target,
155 event_key.identifier,
156 event_key._listen_fn,
157 )
158 target._has_events = True
160 if not retval:
161 if identifier == "before_execute":
162 orig_fn = fn
164 def wrap_before_execute( # type: ignore
165 conn, clauseelement, multiparams, params, execution_options
166 ):
167 orig_fn(
168 conn,
169 clauseelement,
170 multiparams,
171 params,
172 execution_options,
173 )
174 return clauseelement, multiparams, params
176 fn = wrap_before_execute
177 elif identifier == "before_cursor_execute":
178 orig_fn = fn
180 def wrap_before_cursor_execute( # type: ignore
181 conn, cursor, statement, parameters, context, executemany
182 ):
183 orig_fn(
184 conn,
185 cursor,
186 statement,
187 parameters,
188 context,
189 executemany,
190 )
191 return statement, parameters
193 fn = wrap_before_cursor_execute
194 elif retval and identifier not in (
195 "before_execute",
196 "before_cursor_execute",
197 ):
198 raise exc.ArgumentError(
199 "Only the 'before_execute', "
200 "'before_cursor_execute' and 'handle_error' engine "
201 "event listeners accept the 'retval=True' "
202 "argument."
203 )
204 event_key.with_wrapper(fn).base_listen()
206 @event._legacy_signature(
207 "1.4",
208 ["conn", "clauseelement", "multiparams", "params"],
209 lambda conn, clauseelement, multiparams, params, execution_options: (
210 conn,
211 clauseelement,
212 multiparams,
213 params,
214 ),
215 )
216 def before_execute(
217 self,
218 conn: Connection,
219 clauseelement: Executable,
220 multiparams: _CoreMultiExecuteParams,
221 params: _CoreSingleExecuteParams,
222 execution_options: _ExecuteOptions,
223 ) -> Optional[
224 Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams]
225 ]:
226 """Intercept high level execute() events, receiving uncompiled
227 SQL constructs and other objects prior to rendering into SQL.
229 This event is good for debugging SQL compilation issues as well
230 as early manipulation of the parameters being sent to the database,
231 as the parameter lists will be in a consistent format here.
233 This event can be optionally established with the ``retval=True``
234 flag. The ``clauseelement``, ``multiparams``, and ``params``
235 arguments should be returned as a three-tuple in this case::
237 @event.listens_for(Engine, "before_execute", retval=True)
238 def before_execute(conn, clauseelement, multiparams, params):
239 # do something with clauseelement, multiparams, params
240 return clauseelement, multiparams, params
242 :param conn: :class:`_engine.Connection` object
243 :param clauseelement: SQL expression construct, :class:`.Compiled`
244 instance, or string statement passed to
245 :meth:`_engine.Connection.execute`.
246 :param multiparams: Multiple parameter sets, a list of dictionaries.
247 :param params: Single parameter set, a single dictionary.
248 :param execution_options: dictionary of execution
249 options passed along with the statement, if any. This is a merge
250 of all options that will be used, including those of the statement,
251 the connection, and those passed in to the method itself for
252 the 2.0 style of execution.
254 .. versionadded: 1.4
256 .. seealso::
258 :meth:`.before_cursor_execute`
260 """
262 @event._legacy_signature(
263 "1.4",
264 ["conn", "clauseelement", "multiparams", "params", "result"],
265 lambda conn, clauseelement, multiparams, params, execution_options, result: ( # noqa
266 conn,
267 clauseelement,
268 multiparams,
269 params,
270 result,
271 ),
272 )
273 def after_execute(
274 self,
275 conn: Connection,
276 clauseelement: Executable,
277 multiparams: _CoreMultiExecuteParams,
278 params: _CoreSingleExecuteParams,
279 execution_options: _ExecuteOptions,
280 result: Result[Any],
281 ) -> None:
282 """Intercept high level execute() events after execute.
285 :param conn: :class:`_engine.Connection` object
286 :param clauseelement: SQL expression construct, :class:`.Compiled`
287 instance, or string statement passed to
288 :meth:`_engine.Connection.execute`.
289 :param multiparams: Multiple parameter sets, a list of dictionaries.
290 :param params: Single parameter set, a single dictionary.
291 :param execution_options: dictionary of execution
292 options passed along with the statement, if any. This is a merge
293 of all options that will be used, including those of the statement,
294 the connection, and those passed in to the method itself for
295 the 2.0 style of execution.
297 .. versionadded: 1.4
299 :param result: :class:`_engine.CursorResult` generated by the
300 execution.
302 """
304 def before_cursor_execute(
305 self,
306 conn: Connection,
307 cursor: DBAPICursor,
308 statement: str,
309 parameters: _DBAPIAnyExecuteParams,
310 context: Optional[ExecutionContext],
311 executemany: bool,
312 ) -> Optional[Tuple[str, _DBAPIAnyExecuteParams]]:
313 """Intercept low-level cursor execute() events before execution,
314 receiving the string SQL statement and DBAPI-specific parameter list to
315 be invoked against a cursor.
317 This event is a good choice for logging as well as late modifications
318 to the SQL string. It's less ideal for parameter modifications except
319 for those which are specific to a target backend.
321 This event can be optionally established with the ``retval=True``
322 flag. The ``statement`` and ``parameters`` arguments should be
323 returned as a two-tuple in this case::
325 @event.listens_for(Engine, "before_cursor_execute", retval=True)
326 def before_cursor_execute(
327 conn, cursor, statement, parameters, context, executemany
328 ):
329 # do something with statement, parameters
330 return statement, parameters
332 See the example at :class:`_events.ConnectionEvents`.
334 :param conn: :class:`_engine.Connection` object
335 :param cursor: DBAPI cursor object
336 :param statement: string SQL statement, as to be passed to the DBAPI
337 :param parameters: Dictionary, tuple, or list of parameters being
338 passed to the ``execute()`` or ``executemany()`` method of the
339 DBAPI ``cursor``. In some cases may be ``None``.
340 :param context: :class:`.ExecutionContext` object in use. May
341 be ``None``.
342 :param executemany: boolean, if ``True``, this is an ``executemany()``
343 call, if ``False``, this is an ``execute()`` call.
345 .. seealso::
347 :meth:`.before_execute`
349 :meth:`.after_cursor_execute`
351 """
353 def after_cursor_execute(
354 self,
355 conn: Connection,
356 cursor: DBAPICursor,
357 statement: str,
358 parameters: _DBAPIAnyExecuteParams,
359 context: Optional[ExecutionContext],
360 executemany: bool,
361 ) -> None:
362 """Intercept low-level cursor execute() events after execution.
364 :param conn: :class:`_engine.Connection` object
365 :param cursor: DBAPI cursor object. Will have results pending
366 if the statement was a SELECT, but these should not be consumed
367 as they will be needed by the :class:`_engine.CursorResult`.
368 :param statement: string SQL statement, as passed to the DBAPI
369 :param parameters: Dictionary, tuple, or list of parameters being
370 passed to the ``execute()`` or ``executemany()`` method of the
371 DBAPI ``cursor``. In some cases may be ``None``.
372 :param context: :class:`.ExecutionContext` object in use. May
373 be ``None``.
374 :param executemany: boolean, if ``True``, this is an ``executemany()``
375 call, if ``False``, this is an ``execute()`` call.
377 """
379 @event._legacy_signature(
380 "2.0", ["conn", "branch"], converter=lambda conn: (conn, False)
381 )
382 def engine_connect(self, conn: Connection) -> None:
383 """Intercept the creation of a new :class:`_engine.Connection`.
385 This event is called typically as the direct result of calling
386 the :meth:`_engine.Engine.connect` method.
388 It differs from the :meth:`_events.PoolEvents.connect` method, which
389 refers to the actual connection to a database at the DBAPI level;
390 a DBAPI connection may be pooled and reused for many operations.
391 In contrast, this event refers only to the production of a higher level
392 :class:`_engine.Connection` wrapper around such a DBAPI connection.
394 It also differs from the :meth:`_events.PoolEvents.checkout` event
395 in that it is specific to the :class:`_engine.Connection` object,
396 not the
397 DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with,
398 although
399 this DBAPI connection is available here via the
400 :attr:`_engine.Connection.connection` attribute.
401 But note there can in fact
402 be multiple :meth:`_events.PoolEvents.checkout`
403 events within the lifespan
404 of a single :class:`_engine.Connection` object, if that
405 :class:`_engine.Connection`
406 is invalidated and re-established.
408 :param conn: :class:`_engine.Connection` object.
410 .. seealso::
412 :meth:`_events.PoolEvents.checkout`
413 the lower-level pool checkout event
414 for an individual DBAPI connection
416 """
418 def set_connection_execution_options(
419 self, conn: Connection, opts: Dict[str, Any]
420 ) -> None:
421 """Intercept when the :meth:`_engine.Connection.execution_options`
422 method is called.
424 This method is called after the new :class:`_engine.Connection`
425 has been
426 produced, with the newly updated execution options collection, but
427 before the :class:`.Dialect` has acted upon any of those new options.
429 Note that this method is not called when a new
430 :class:`_engine.Connection`
431 is produced which is inheriting execution options from its parent
432 :class:`_engine.Engine`; to intercept this condition, use the
433 :meth:`_events.ConnectionEvents.engine_connect` event.
435 :param conn: The newly copied :class:`_engine.Connection` object
437 :param opts: dictionary of options that were passed to the
438 :meth:`_engine.Connection.execution_options` method.
439 This dictionary may be modified in place to affect the ultimate
440 options which take effect.
442 .. versionadded:: 2.0 the ``opts`` dictionary may be modified
443 in place.
446 .. seealso::
448 :meth:`_events.ConnectionEvents.set_engine_execution_options`
449 - event
450 which is called when :meth:`_engine.Engine.execution_options`
451 is called.
454 """
456 def set_engine_execution_options(
457 self, engine: Engine, opts: Dict[str, Any]
458 ) -> None:
459 """Intercept when the :meth:`_engine.Engine.execution_options`
460 method is called.
462 The :meth:`_engine.Engine.execution_options` method produces a shallow
463 copy of the :class:`_engine.Engine` which stores the new options.
464 That new
465 :class:`_engine.Engine` is passed here.
466 A particular application of this
467 method is to add a :meth:`_events.ConnectionEvents.engine_connect`
468 event
469 handler to the given :class:`_engine.Engine`
470 which will perform some per-
471 :class:`_engine.Connection` task specific to these execution options.
473 :param conn: The newly copied :class:`_engine.Engine` object
475 :param opts: dictionary of options that were passed to the
476 :meth:`_engine.Connection.execution_options` method.
477 This dictionary may be modified in place to affect the ultimate
478 options which take effect.
480 .. versionadded:: 2.0 the ``opts`` dictionary may be modified
481 in place.
483 .. seealso::
485 :meth:`_events.ConnectionEvents.set_connection_execution_options`
486 - event
487 which is called when :meth:`_engine.Connection.execution_options`
488 is
489 called.
491 """
493 def engine_disposed(self, engine: Engine) -> None:
494 """Intercept when the :meth:`_engine.Engine.dispose` method is called.
496 The :meth:`_engine.Engine.dispose` method instructs the engine to
497 "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and
498 replaces it with a new one. Disposing of the old pool has the
499 effect that existing checked-in connections are closed. The new
500 pool does not establish any new connections until it is first used.
502 This event can be used to indicate that resources related to the
503 :class:`_engine.Engine` should also be cleaned up,
504 keeping in mind that the
505 :class:`_engine.Engine`
506 can still be used for new requests in which case
507 it re-acquires connection resources.
509 """
511 def begin(self, conn: Connection) -> None:
512 """Intercept begin() events.
514 :param conn: :class:`_engine.Connection` object
516 """
518 def rollback(self, conn: Connection) -> None:
519 """Intercept rollback() events, as initiated by a
520 :class:`.Transaction`.
522 Note that the :class:`_pool.Pool` also "auto-rolls back"
523 a DBAPI connection upon checkin, if the ``reset_on_return``
524 flag is set to its default value of ``'rollback'``.
525 To intercept this
526 rollback, use the :meth:`_events.PoolEvents.reset` hook.
528 :param conn: :class:`_engine.Connection` object
530 .. seealso::
532 :meth:`_events.PoolEvents.reset`
534 """
536 def commit(self, conn: Connection) -> None:
537 """Intercept commit() events, as initiated by a
538 :class:`.Transaction`.
540 Note that the :class:`_pool.Pool` may also "auto-commit"
541 a DBAPI connection upon checkin, if the ``reset_on_return``
542 flag is set to the value ``'commit'``. To intercept this
543 commit, use the :meth:`_events.PoolEvents.reset` hook.
545 :param conn: :class:`_engine.Connection` object
546 """
548 def savepoint(self, conn: Connection, name: str) -> None:
549 """Intercept savepoint() events.
551 :param conn: :class:`_engine.Connection` object
552 :param name: specified name used for the savepoint.
554 """
556 def rollback_savepoint(
557 self, conn: Connection, name: str, context: None
558 ) -> None:
559 """Intercept rollback_savepoint() events.
561 :param conn: :class:`_engine.Connection` object
562 :param name: specified name used for the savepoint.
563 :param context: not used
565 """
566 # TODO: deprecate "context"
568 def release_savepoint(
569 self, conn: Connection, name: str, context: None
570 ) -> None:
571 """Intercept release_savepoint() events.
573 :param conn: :class:`_engine.Connection` object
574 :param name: specified name used for the savepoint.
575 :param context: not used
577 """
578 # TODO: deprecate "context"
580 def begin_twophase(self, conn: Connection, xid: Any) -> None:
581 """Intercept begin_twophase() events.
583 :param conn: :class:`_engine.Connection` object
584 :param xid: two-phase XID identifier
586 """
588 def prepare_twophase(self, conn: Connection, xid: Any) -> None:
589 """Intercept prepare_twophase() events.
591 :param conn: :class:`_engine.Connection` object
592 :param xid: two-phase XID identifier
593 """
595 def rollback_twophase(
596 self, conn: Connection, xid: Any, is_prepared: bool
597 ) -> None:
598 """Intercept rollback_twophase() events.
600 :param conn: :class:`_engine.Connection` object
601 :param xid: two-phase XID identifier
602 :param is_prepared: boolean, indicates if
603 :meth:`.TwoPhaseTransaction.prepare` was called.
605 """
607 def commit_twophase(
608 self, conn: Connection, xid: Any, is_prepared: bool
609 ) -> None:
610 """Intercept commit_twophase() events.
612 :param conn: :class:`_engine.Connection` object
613 :param xid: two-phase XID identifier
614 :param is_prepared: boolean, indicates if
615 :meth:`.TwoPhaseTransaction.prepare` was called.
617 """
620class DialectEvents(event.Events[Dialect]):
621 """event interface for execution-replacement functions.
623 These events allow direct instrumentation and replacement
624 of key dialect functions which interact with the DBAPI.
626 .. note::
628 :class:`.DialectEvents` hooks should be considered **semi-public**
629 and experimental.
630 These hooks are not for general use and are only for those situations
631 where intricate re-statement of DBAPI mechanics must be injected onto
632 an existing dialect. For general-use statement-interception events,
633 please use the :class:`_events.ConnectionEvents` interface.
635 .. seealso::
637 :meth:`_events.ConnectionEvents.before_cursor_execute`
639 :meth:`_events.ConnectionEvents.before_execute`
641 :meth:`_events.ConnectionEvents.after_cursor_execute`
643 :meth:`_events.ConnectionEvents.after_execute`
645 """
647 _target_class_doc = "SomeEngine"
648 _dispatch_target = Dialect
650 @classmethod
651 def _listen(
652 cls,
653 event_key: event._EventKey[Dialect],
654 *,
655 retval: bool = False,
656 **kw: Any,
657 ) -> None:
658 target = event_key.dispatch_target
660 target._has_events = True
661 event_key.base_listen()
663 @classmethod
664 def _accept_with(
665 cls,
666 target: Union[Engine, Type[Engine], Dialect, Type[Dialect]],
667 identifier: str,
668 ) -> Optional[Union[Dialect, Type[Dialect]]]:
669 if isinstance(target, type):
670 if issubclass(target, Engine):
671 return Dialect
672 elif issubclass(target, Dialect):
673 return target
674 elif isinstance(target, Engine):
675 return target.dialect
676 elif isinstance(target, Dialect):
677 return target
678 elif isinstance(target, Connection) and identifier == "handle_error":
679 raise exc.InvalidRequestError(
680 "The handle_error() event hook as of SQLAlchemy 2.0 is "
681 "established on the Dialect, and may only be applied to the "
682 "Engine as a whole or to a specific Dialect as a whole, "
683 "not on a per-Connection basis."
684 )
685 elif hasattr(target, "_no_async_engine_events"):
686 target._no_async_engine_events()
687 else:
688 return None
690 def handle_error(
691 self, exception_context: ExceptionContext
692 ) -> Optional[BaseException]:
693 r"""Intercept all exceptions processed by the
694 :class:`_engine.Dialect`, typically but not limited to those
695 emitted within the scope of a :class:`_engine.Connection`.
697 .. versionchanged:: 2.0 the :meth:`.DialectEvents.handle_error` event
698 is moved to the :class:`.DialectEvents` class, moved from the
699 :class:`.ConnectionEvents` class, so that it may also participate in
700 the "pre ping" operation configured with the
701 :paramref:`_sa.create_engine.pool_pre_ping` parameter. The event
702 remains registered by using the :class:`_engine.Engine` as the event
703 target, however note that using the :class:`_engine.Connection` as
704 an event target for :meth:`.DialectEvents.handle_error` is no longer
705 supported.
707 This includes all exceptions emitted by the DBAPI as well as
708 within SQLAlchemy's statement invocation process, including
709 encoding errors and other statement validation errors. Other areas
710 in which the event is invoked include transaction begin and end,
711 result row fetching, cursor creation.
713 Note that :meth:`.handle_error` may support new kinds of exceptions
714 and new calling scenarios at *any time*. Code which uses this
715 event must expect new calling patterns to be present in minor
716 releases.
718 To support the wide variety of members that correspond to an exception,
719 as well as to allow extensibility of the event without backwards
720 incompatibility, the sole argument received is an instance of
721 :class:`.ExceptionContext`. This object contains data members
722 representing detail about the exception.
724 Use cases supported by this hook include:
726 * read-only, low-level exception handling for logging and
727 debugging purposes
728 * Establishing whether a DBAPI connection error message indicates
729 that the database connection needs to be reconnected, including
730 for the "pre_ping" handler used by **some** dialects
731 * Establishing or disabling whether a connection or the owning
732 connection pool is invalidated or expired in response to a
733 specific exception
734 * exception re-writing
736 The hook is called while the cursor from the failed operation
737 (if any) is still open and accessible. Special cleanup operations
738 can be called on this cursor; SQLAlchemy will attempt to close
739 this cursor subsequent to this hook being invoked.
741 As of SQLAlchemy 2.0, the "pre_ping" handler enabled using the
742 :paramref:`_sa.create_engine.pool_pre_ping` parameter will also
743 participate in the :meth:`.handle_error` process, **for those dialects
744 that rely upon disconnect codes to detect database liveness**. Note
745 that some dialects such as psycopg, psycopg2, and most MySQL dialects
746 make use of a native ``ping()`` method supplied by the DBAPI which does
747 not make use of disconnect codes.
749 .. versionchanged:: 2.0.0 The :meth:`.DialectEvents.handle_error`
750 event hook participates in connection pool "pre-ping" operations.
751 Within this usage, the :attr:`.ExceptionContext.engine` attribute
752 will be ``None``, however the :class:`.Dialect` in use is always
753 available via the :attr:`.ExceptionContext.dialect` attribute.
755 .. versionchanged:: 2.0.5 Added :attr:`.ExceptionContext.is_pre_ping`
756 attribute which will be set to ``True`` when the
757 :meth:`.DialectEvents.handle_error` event hook is triggered within
758 a connection pool pre-ping operation.
760 .. versionchanged:: 2.0.5 An issue was repaired that allows for the
761 PostgreSQL ``psycopg`` and ``psycopg2`` drivers, as well as all
762 MySQL drivers, to properly participate in the
763 :meth:`.DialectEvents.handle_error` event hook during
764 connection pool "pre-ping" operations; previously, the
765 implementation was non-working for these drivers.
768 A handler function has two options for replacing
769 the SQLAlchemy-constructed exception into one that is user
770 defined. It can either raise this new exception directly, in
771 which case all further event listeners are bypassed and the
772 exception will be raised, after appropriate cleanup as taken
773 place::
775 @event.listens_for(Engine, "handle_error")
776 def handle_exception(context):
777 if isinstance(
778 context.original_exception, psycopg2.OperationalError
779 ) and "failed" in str(context.original_exception):
780 raise MySpecialException("failed operation")
782 .. warning:: Because the
783 :meth:`_events.DialectEvents.handle_error`
784 event specifically provides for exceptions to be re-thrown as
785 the ultimate exception raised by the failed statement,
786 **stack traces will be misleading** if the user-defined event
787 handler itself fails and throws an unexpected exception;
788 the stack trace may not illustrate the actual code line that
789 failed! It is advised to code carefully here and use
790 logging and/or inline debugging if unexpected exceptions are
791 occurring.
793 Alternatively, a "chained" style of event handling can be
794 used, by configuring the handler with the ``retval=True``
795 modifier and returning the new exception instance from the
796 function. In this case, event handling will continue onto the
797 next handler. The "chained" exception is available using
798 :attr:`.ExceptionContext.chained_exception`::
800 @event.listens_for(Engine, "handle_error", retval=True)
801 def handle_exception(context):
802 if (
803 context.chained_exception is not None
804 and "special" in context.chained_exception.message
805 ):
806 return MySpecialException(
807 "failed", cause=context.chained_exception
808 )
810 Handlers that return ``None`` may be used within the chain; when
811 a handler returns ``None``, the previous exception instance,
812 if any, is maintained as the current exception that is passed onto the
813 next handler.
815 When a custom exception is raised or returned, SQLAlchemy raises
816 this new exception as-is, it is not wrapped by any SQLAlchemy
817 object. If the exception is not a subclass of
818 :class:`sqlalchemy.exc.StatementError`,
819 certain features may not be available; currently this includes
820 the ORM's feature of adding a detail hint about "autoflush" to
821 exceptions raised within the autoflush process.
823 :param context: an :class:`.ExceptionContext` object. See this
824 class for details on all available members.
827 .. seealso::
829 :ref:`pool_new_disconnect_codes`
831 """
833 def do_connect(
834 self,
835 dialect: Dialect,
836 conn_rec: ConnectionPoolEntry,
837 cargs: Tuple[Any, ...],
838 cparams: Dict[str, Any],
839 ) -> Optional[DBAPIConnection]:
840 """Receive connection arguments before a connection is made.
842 This event is useful in that it allows the handler to manipulate the
843 cargs and/or cparams collections that control how the DBAPI
844 ``connect()`` function will be called. ``cargs`` will always be a
845 Python list that can be mutated in-place, and ``cparams`` a Python
846 dictionary that may also be mutated::
848 e = create_engine("postgresql+psycopg2://user@host/dbname")
851 @event.listens_for(e, "do_connect")
852 def receive_do_connect(dialect, conn_rec, cargs, cparams):
853 cparams["password"] = "some_password"
855 The event hook may also be used to override the call to ``connect()``
856 entirely, by returning a non-``None`` DBAPI connection object::
858 e = create_engine("postgresql+psycopg2://user@host/dbname")
861 @event.listens_for(e, "do_connect")
862 def receive_do_connect(dialect, conn_rec, cargs, cparams):
863 return psycopg2.connect(*cargs, **cparams)
865 .. seealso::
867 :ref:`custom_dbapi_args`
869 """
871 def do_executemany(
872 self,
873 cursor: DBAPICursor,
874 statement: str,
875 parameters: _DBAPIMultiExecuteParams,
876 context: ExecutionContext,
877 ) -> Optional[Literal[True]]:
878 """Receive a cursor to have executemany() called.
880 Return the value True to halt further events from invoking,
881 and to indicate that the cursor execution has already taken
882 place within the event handler.
884 """
886 def do_execute_no_params(
887 self, cursor: DBAPICursor, statement: str, context: ExecutionContext
888 ) -> Optional[Literal[True]]:
889 """Receive a cursor to have execute() with no parameters called.
891 Return the value True to halt further events from invoking,
892 and to indicate that the cursor execution has already taken
893 place within the event handler.
895 """
897 def do_execute(
898 self,
899 cursor: DBAPICursor,
900 statement: str,
901 parameters: _DBAPISingleExecuteParams,
902 context: ExecutionContext,
903 ) -> Optional[Literal[True]]:
904 """Receive a cursor to have execute() called.
906 Return the value True to halt further events from invoking,
907 and to indicate that the cursor execution has already taken
908 place within the event handler.
910 """
912 def do_setinputsizes(
913 self,
914 inputsizes: Dict[BindParameter[Any], Any],
915 cursor: DBAPICursor,
916 statement: str,
917 parameters: _DBAPIAnyExecuteParams,
918 context: ExecutionContext,
919 ) -> None:
920 """Receive the setinputsizes dictionary for possible modification.
922 This event is emitted in the case where the dialect makes use of the
923 DBAPI ``cursor.setinputsizes()`` method which passes information about
924 parameter binding for a particular statement. The given
925 ``inputsizes`` dictionary will contain :class:`.BindParameter` objects
926 as keys, linked to DBAPI-specific type objects as values; for
927 parameters that are not bound, they are added to the dictionary with
928 ``None`` as the value, which means the parameter will not be included
929 in the ultimate setinputsizes call. The event may be used to inspect
930 and/or log the datatypes that are being bound, as well as to modify the
931 dictionary in place. Parameters can be added, modified, or removed
932 from this dictionary. Callers will typically want to inspect the
933 :attr:`.BindParameter.type` attribute of the given bind objects in
934 order to make decisions about the DBAPI object.
936 After the event, the ``inputsizes`` dictionary is converted into
937 an appropriate datastructure to be passed to ``cursor.setinputsizes``;
938 either a list for a positional bound parameter execution style,
939 or a dictionary of string parameter keys to DBAPI type objects for
940 a named bound parameter execution style.
942 The setinputsizes hook overall is only used for dialects which include
943 the flag ``use_setinputsizes=True``. Dialects which use this
944 include python-oracledb, cx_Oracle, pg8000, asyncpg, and pyodbc
945 dialects.
947 .. note::
949 For use with pyodbc, the ``use_setinputsizes`` flag
950 must be passed to the dialect, e.g.::
952 create_engine("mssql+pyodbc://...", use_setinputsizes=True)
954 .. seealso::
956 :ref:`mssql_pyodbc_setinputsizes`
958 .. versionadded:: 1.2.9
960 .. seealso::
962 :ref:`cx_oracle_setinputsizes`
964 """
965 pass