Core Events

Dieser Abschnitt beschreibt die in SQLAlchemy Core bereitgestellten Event-Schnittstellen. Eine Einführung in die Event-Listener-API finden Sie unter Events. ORM-Events werden in ORM Events beschrieben.

Objektname Beschreibung

Events

Definieren Sie Event-Listener-Funktionen für einen bestimmten Zieltyp.
class sqlalchemy.event.base.Events

Definieren Sie Event-Listener-Funktionen für einen bestimmten Zieltyp.

Mitglieder

dispatch

Klassensignatur

class sqlalchemy.event.Events (sqlalchemy.event._HasEventsDispatch)

attribut sqlalchemy.event.base.Events.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.EventsDispatch object>

verweist zurück auf die _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

Connection Pool Events

Objektname Beschreibung

PoolEvents

Verfügbare Events für Pool.

PoolResetState

beschreibt den Zustand einer DBAPI-Verbindung, während sie an das PoolEvents.reset() Event des Connection Pools übergeben wird.
class sqlalchemy.events.PoolEvents

Verfügbare Events für Pool.

Die Methoden hier definieren den Namen eines Events sowie die Namen von Mitgliedern, die an Listener-Funktionen übergeben werden.

z. B.

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)

Neben der Akzeptanz der Klasse Pool und von Pool-Instanzen akzeptiert PoolEvents auch Engine-Objekte und die Klasse Engine als Ziele, die auf das Attribut .pool des gegebenen Engines oder die Klasse Pool aufgelöst werden.

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

# will associate with engine.pool
event.listen(engine, "checkout", my_on_checkout)

Mitglieder

checkin(), checkout(), close(), close_detached(), connect(), detach(), dispatch, first_connect(), invalidate(), reset(), soft_invalidate()

Klassensignatur

class sqlalchemy.events.PoolEvents (sqlalchemy.event.Events)

method sqlalchemy.events.PoolEvents.checkin(dbapi_connection: DBAPIConnection | None, connection_record: ConnectionPoolEntry) → None

Wird aufgerufen, wenn eine Verbindung zum Pool zurückkehrt.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'checkin')
def receive_checkin(dbapi_connection, connection_record):
    "listen for the 'checkin' event"

    # ... (event handling logic) ...

Beachten Sie, dass die Verbindung geschlossen sein kann und None sein kann, wenn die Verbindung ungültig geworden ist. checkin wird nicht für getrennte Verbindungen aufgerufen. (Sie kehren nicht zum Pool zurück.)

Parameter:
method sqlalchemy.events.PoolEvents.checkout(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, connection_proxy: PoolProxiedConnection) → None

Wird aufgerufen, wenn eine Verbindung aus dem Pool abgerufen wird.

Beispielhafte Argumentübergaben

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) ...
Parameter:

Wenn Sie eine DisconnectionError auslösen, wird die aktuelle Verbindung entsorgt und eine neue Verbindung abgerufen. Die Verarbeitung aller Checkout-Listener wird abgebrochen und mit der neuen Verbindung neu gestartet.

Siehe auch

ConnectionEvents.engine_connect() - ein ähnliches Event, das beim Erstellen einer neuen Connection auftritt.

method sqlalchemy.events.PoolEvents.close(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None

Wird aufgerufen, wenn eine DBAPI-Verbindung geschlossen wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'close')
def receive_close(dbapi_connection, connection_record):
    "listen for the 'close' event"

    # ... (event handling logic) ...

Das Event wird vor dem Schließen ausgelöst.

Das Schließen einer Verbindung kann fehlschlagen; typischerweise liegt dies daran, dass die Verbindung bereits geschlossen ist. Wenn der Schließvorgang fehlschlägt, wird die Verbindung verworfen.

Das Event close() entspricht einer Verbindung, die noch mit dem Pool verbunden ist. Um Schließungsereignisse für getrennte Verbindungen abzufangen, verwenden Sie close_detached().

Parameter:
method sqlalchemy.events.PoolEvents.close_detached(dbapi_connection: DBAPIConnection) → None

Wird aufgerufen, wenn eine getrennte DBAPI-Verbindung geschlossen wird.

Beispielhafte Argumentübergaben

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) ...

Das Event wird vor dem Schließen ausgelöst.

Das Schließen einer Verbindung kann fehlschlagen; typischerweise liegt dies daran, dass die Verbindung bereits geschlossen ist. Wenn der Schließvorgang fehlschlägt, wird die Verbindung verworfen.

Parameter:

dbapi_connection – eine DBAPI-Verbindung. Das Attribut ConnectionPoolEntry.dbapi_connection.

method sqlalchemy.events.PoolEvents.connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None

Wird zu dem Zeitpunkt aufgerufen, an dem eine bestimmte DBAPI-Verbindung zum ersten Mal für einen bestimmten Pool erstellt wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'connect')
def receive_connect(dbapi_connection, connection_record):
    "listen for the 'connect' event"

    # ... (event handling logic) ...

Dieses Event ermöglicht es, den Zeitpunkt direkt nach der Verwendung der .connect() Methode auf Modulebene des DBAPI-Moduls zur Erzeugung einer neuen DBAPI-Verbindung abzufangen.

Parameter:
method sqlalchemy.events.PoolEvents.detach(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None

Wird aufgerufen, wenn eine DBAPI-Verbindung von einem Pool „getrennt“ wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'detach')
def receive_detach(dbapi_connection, connection_record):
    "listen for the 'detach' event"

    # ... (event handling logic) ...

Dieses Event wird nach dem Trennen ausgelöst. Die Verbindung ist nicht mehr mit dem angegebenen Verbindungsdatensatz verbunden.

Parameter:
attribut sqlalchemy.events.PoolEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.PoolEventsDispatch object>

verweist zurück auf die _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

method sqlalchemy.events.PoolEvents.first_connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None

Wird genau einmal aufgerufen, wenn zum ersten Mal eine DBAPI-Verbindung von einem bestimmten Pool abgerufen wird.

Beispielhafte Argumentübergaben

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) ...

Der Grund für PoolEvents.first_connect() ist die Ermittlung von Informationen über eine bestimmte Reihe von Datenbankverbindungen basierend auf den Einstellungen, die für alle Verbindungen verwendet werden. Da ein bestimmter Pool sich auf eine einzige „Erzeuger“-Funktion bezieht (was im Sinne eines Engine auf die verwendete URL und Verbindungsoptionen verweist), ist es im Allgemeinen gültig, Beobachtungen über eine einzelne Verbindung zu machen, die sicher für alle nachfolgenden Verbindungen gültig angenommen werden können, wie z.B. die Datenbankversion, die Server- und Client-Encoding-Einstellungen, Kollationseinstellungen und viele andere.

Parameter:
method sqlalchemy.events.PoolEvents.invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None

Wird aufgerufen, wenn eine DBAPI-Verbindung als „ungültig“ markiert werden soll.

Beispielhafte Argumentübergaben

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) ...

Dieses Event wird jedes Mal aufgerufen, wenn die Methode ConnectionPoolEntry.invalidate() aufgerufen wird, entweder durch API-Nutzung oder durch „automatische Ungültigmachung“, ohne das Flag soft.

Das Event tritt auf, bevor ein letzter Versuch unternommen wird, die Verbindung mit .close() zu schließen.

Parameter:

Siehe auch

Mehr über Invalidation

method sqlalchemy.events.PoolEvents.reset(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, reset_state: PoolResetState) → None

Wird vor dem „Zurücksetzen“ einer gepoolten Verbindung aufgerufen.

Beispielhafte Argumentübergaben

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) ...

Geändert in Version 2.0: Das Event PoolEvents.reset() akzeptiert nun die Argumente PoolEvents.reset.dbapi_connection, PoolEvents.reset.connection_record, PoolEvents.reset.reset_state. Die Unterstützung für Listener-Funktionen, die die vorherigen Argument-Signaturen (wie oben aufgeführt) als „veraltet“ akzeptieren, wird in einer zukünftigen Version entfernt.

Dieses Event repräsentiert, wann die Methode rollback() auf der DBAPI-Verbindung aufgerufen wird, bevor sie an den Pool zurückgegeben oder verworfen wird. Eine benutzerdefinierte „Zurücksetzen“-Strategie kann mithilfe dieses Event-Hooks implementiert werden, der auch mit der Deaktivierung des Standard-„Zurücksetzen“-Verhaltens über den Parameter Pool.reset_on_return kombiniert werden kann.

Der Hauptunterschied zwischen den Events PoolEvents.reset() und PoolEvents.checkin() besteht darin, dass PoolEvents.reset() nicht nur für gepoolte Verbindungen aufgerufen wird, die an den Pool zurückgegeben werden, sondern auch für Verbindungen, die mit der Methode Connection.detach() getrennt wurden, sowie für asyncio-Verbindungen, die aufgrund der Garbage Collection von Verbindungen verworfen werden, bevor die Verbindung eingecheckt wurde.

Beachten Sie, dass das Event **nicht** für Verbindungen aufgerufen wird, die mit Connection.invalidate() ungültig gemacht wurden. Diese Events können über die Event-Hooks PoolEvents.soft_invalidate() und PoolEvents.invalidate() abgefangen werden, und alle „Verbindung schließen“-Events können über PoolEvents.close() abgefangen werden.

Das Event PoolEvents.reset() wird normalerweise vom Event PoolEvents.checkin() gefolgt, außer in Fällen, in denen die Verbindung unmittelbar nach dem Zurücksetzen verworfen wird.

Parameter:

Siehe auch

Zurücksetzen bei Rückgabe

ConnectionEvents.rollback()

ConnectionEvents.commit()

methode sqlalchemy.events.PoolEvents.soft_invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None

Wird aufgerufen, wenn eine DBAPI-Verbindung "weich ungültig" gemacht werden soll.

Beispielhafte Argumentübergaben

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) ...

Dieses Ereignis wird jedes Mal aufgerufen, wenn die Methode ConnectionPoolEntry.invalidate() mit dem Flag soft aufgerufen wird.

Eine "weiche Ungültigmachung" bedeutet, dass der Verbindungseintrag, der diese Verbindung verwaltet, eine Wiederverbindung erzwingt, nachdem die aktuelle Verbindung zurückgegeben wurde. Die DBAPI-Verbindung wird an diesem Punkt nicht aktiv geschlossen.

Parameter:
klasse sqlalchemy.events.PoolResetState

beschreibt den Zustand einer DBAPI-Verbindung, während sie an das PoolEvents.reset() Event des Connection Pools übergeben wird.

Mitglieder

asyncio_safe, terminate_only, transaction_was_reset

Neu in Version 2.0.0b3.

attribut sqlalchemy.events.PoolResetState.asyncio_safe: bool

Gibt an, ob die Zurücksetzung innerhalb eines Gültigkeitsbereichs stattfindet, in dem für asyncio-Anwendungen eine umschließende Ereignisschleife erwartet wird.

Ist Falsch, wenn die Verbindung durch Garbage Collection bereinigt wird.

attribut sqlalchemy.events.PoolResetState.terminate_only: bool

Gibt an, ob die Verbindung sofort beendet und nicht an den Pool zurückgegeben werden soll.

Dies geschieht bei Verbindungen, die ungültig gemacht wurden, sowie bei asyncio-Verbindungen, die vom aufrufenden Code nicht sauber behandelt wurden und stattdessen durch Garbage Collection bereinigt werden. Letzteres gilt, da bei der Garbage Collection keine Operationen sicher auf asyncio-Verbindungen ausgeführt werden können, da möglicherweise keine Ereignisschleife vorhanden ist.

attribut sqlalchemy.events.PoolResetState.transaction_was_reset: bool

Gibt an, ob die Transaktion auf der DBAPI-Verbindung bereits vom Connection-Objekt "zurückgesetzt" wurde.

Dieser boolesche Wert ist True, wenn der Connection transaktionalen Zustand aufwies, der dann nicht mit den Methoden Connection.rollback() oder Connection.commit() geschlossen wurde; stattdessen wurde die Transaktion inline innerhalb der Methode Connection.close() geschlossen, sodass garantiert ist, dass sie bei Erreichen dieses Ereignisses nicht mehr vorhanden ist.

SQL-Ausführungs- und Verbindungsereignisse

Objektname Beschreibung

ConnectionEvents

Verfügbare Ereignisse für Connection und Engine.

DialectEvents

Schnittstelle für Ereignisse von Funktionen, die die Ausführung ersetzen.
klasse sqlalchemy.events.ConnectionEvents

Verfügbare Ereignisse für Connection und Engine.

Die Methoden hier definieren den Namen eines Events sowie die Namen von Mitgliedern, die an Listener-Funktionen übergeben werden.

Ein Ereignis-Listener kann mit jeder Connection- oder Engine-Klasse oder -Instanz verknüpft werden, wie z. B. eine Engine, z. B.:

from sqlalchemy import event, create_engine


def before_cursor_execute(
    conn, cursor, statement, parameters, context, executemany
):
    log.info("Received statement: %s", statement)


engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
event.listen(engine, "before_cursor_execute", before_cursor_execute)

oder mit einer bestimmten Connection

with engine.begin() as conn:

    @event.listens_for(conn, "before_cursor_execute")
    def before_cursor_execute(
        conn, cursor, statement, parameters, context, executemany
    ):
        log.info("Received statement: %s", statement)

Wenn die Methoden mit einem Parameter statement aufgerufen werden, wie z. B. in after_cursor_execute() oder before_cursor_execute(), ist das Statement die exakte SQL-Zeichenkette, die für die Übertragung an den DBAPI-cursor im Dialect der Verbindung vorbereitet wurde.

Die Ereignisse before_execute() und before_cursor_execute() können auch mit dem Flag retval=True eingerichtet werden, was die Änderung des Statements und der Parameter ermöglicht, die an die Datenbank gesendet werden. Das Ereignis before_cursor_execute() ist hier besonders nützlich, um ad-hoc String-Transformationen, wie z. B. Kommentare, zu allen Ausführungen hinzuzufügen.

from sqlalchemy.engine import Engine
from sqlalchemy import event


@event.listens_for(Engine, "before_cursor_execute", retval=True)
def comment_sql_calls(
    conn, cursor, statement, parameters, context, executemany
):
    statement = statement + " -- some comment"
    return statement, parameters

Hinweis

ConnectionEvents können für jede Kombination von Engine, Connection sowie für Instanzen jeder dieser Klassen eingerichtet werden. Ereignisse über alle vier Gültigkeitsbereiche hinweg werden für eine gegebene Instanz von Connection ausgelöst. Aus Leistungsgründen bestimmt das Connection-Objekt jedoch zum Zeitpunkt der Instanziierung, ob für seine übergeordnete Engine Ereignis-Listener eingerichtet sind. Ereignis-Listener, die zur Engine-Klasse oder zu einer Instanz von Engine hinzugefügt wurden, *nachdem* eine abhängige Connection-Instanz instanziiert wurde, sind normalerweise *nicht* auf dieser Connection-Instanz verfügbar. Die neu hinzugefügten Listener werden stattdessen für Connection-Instanzen wirksam, die nach dem Einrichten dieser Ereignis-Listener in der übergeordneten Engine-Klasse oder -Instanz erstellt wurden.

Parameter:

retval=False – Gilt nur für die Ereignisse before_execute() und before_cursor_execute(). Wenn True, muss die benutzerdefinierte Ereignisfunktion einen Rückgabewert haben, der ein Tupel von Parametern ist, die das gegebene Statement und die Parameter ersetzen. Siehe diese Methoden für eine Beschreibung der spezifischen Rückgabeargumente.

Mitglieder

after_cursor_execute(), after_execute(), before_cursor_execute(), before_execute(), begin(), begin_twophase(), commit(), commit_twophase(), dispatch, engine_connect(), engine_disposed(), prepare_twophase(), release_savepoint(), rollback(), rollback_savepoint(), rollback_twophase(), savepoint(), set_connection_execution_options(), set_engine_execution_options()

Klassensignatur

class sqlalchemy.events.ConnectionEvents (sqlalchemy.event.Events)

methode sqlalchemy.events.ConnectionEvents.after_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext | None, executemany: bool) → None

Abfangen von Low-Level-Cursor-execute()-Ereignissen nach der Ausführung.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_cursor_execute')
def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'after_cursor_execute' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection-Objekt

  • cursor – DBAPI-Cursor-Objekt. Es werden Ergebnisse ausstehen, wenn das Statement ein SELECT war, diese sollten jedoch nicht konsumiert werden, da sie für das CursorResult benötigt werden.

  • statement – Zeichenkette SQL-Statement, wie an die DBAPI übergeben

  • parameters – Dictionary, Tupel oder Liste von Parametern, die an die Methode execute() oder executemany() des DBAPI-cursor übergeben werden. In einigen Fällen kann dies None sein.

  • context – ExecutionContext-Objekt in Gebrauch. Kann None sein.

  • executemany – boolesch, wenn True, handelt es sich um einen Aufruf von executemany(), wenn False, handelt es sich um einen Aufruf von execute().

methode sqlalchemy.events.ConnectionEvents.after_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions, result: Result[Any]) → None

Abfangen von High-Level-execute()-Ereignissen nach der Ausführung.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, execution_options, result):
    "listen for the 'after_execute' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, result):
    "listen for the 'after_execute' event"

    # ... (event handling logic) ...

Geändert in Version 1.4: Das Ereignis ConnectionEvents.after_execute() akzeptiert jetzt die Argumente ConnectionEvents.after_execute.conn, ConnectionEvents.after_execute.clauseelement, ConnectionEvents.after_execute.multiparams, ConnectionEvents.after_execute.params, ConnectionEvents.after_execute.execution_options, ConnectionEvents.after_execute.result. Die Unterstützung für Listener-Funktionen, die die vorherigen Argumentsignaturen (oben aufgeführt) als "veraltet" akzeptieren, wird in einer zukünftigen Version entfernt.

Parameter:

  • conn – Connection-Objekt

  • clauseelement – SQL-Ausdruckskonstrukt, Compiled-Instanz oder Zeichenketten-Statement, das an Connection.execute() übergeben wurde.

  • multiparams – Mehrere Parametersätze, eine Liste von Dictionaries.

  • params – Einzelner Parametersatz, ein einzelnes Dictionary.

  • execution_options –

    Dictionary der mit dem Statement übergebenen Ausführungsoptionen, falls vorhanden. Dies ist eine Zusammenführung aller zu verwendenden Optionen, einschließlich derer des Statements, der Verbindung und derer, die für den 2.0-Stil der Ausführung selbst an die Methode übergeben wurden.

  • result – CursorResult, der durch die Ausführung generiert wurde.

methode sqlalchemy.events.ConnectionEvents.before_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext | None, executemany: bool) → Tuple[str, _DBAPIAnyExecuteParams] | None

Abfangen von Low-Level-Cursor-execute()-Ereignissen vor der Ausführung, wobei die Zeichenkette des SQL-Statements und die DBAPI-spezifische Parameterliste empfangen werden, die gegen einen Cursor aufgerufen werden soll.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_cursor_execute')
def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'before_cursor_execute' event"

    # ... (event handling logic) ...

Dieses Ereignis ist eine gute Wahl für die Protokollierung sowie für späte Änderungen der SQL-Zeichenkette. Es ist weniger ideal für Parameteränderungen, außer für diejenigen, die spezifisch für ein Ziel-Backend sind.

Dieses Ereignis kann optional mit dem Flag retval=True eingerichtet werden. In diesem Fall sollten die Argumente statement und parameters als Zweiertupel zurückgegeben werden.

@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

Siehe das Beispiel unter ConnectionEvents.

Parameter:

  • conn – Connection-Objekt

  • cursor – DBAPI-Cursor-Objekt

  • statement – Zeichenkette SQL-Statement, wie es an die DBAPI übergeben werden soll

  • parameters – Dictionary, Tupel oder Liste von Parametern, die an die Methode execute() oder executemany() des DBAPI-cursor übergeben werden. In einigen Fällen kann dies None sein.

  • context – ExecutionContext-Objekt in Gebrauch. Kann None sein.

  • executemany – boolesch, wenn True, handelt es sich um einen Aufruf von executemany(), wenn False, handelt es sich um einen Aufruf von execute().

Siehe auch

before_execute()

after_cursor_execute()

methode sqlalchemy.events.ConnectionEvents.before_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions) → Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams] | None

Abfangen von High-Level-execute()-Ereignissen vor der Ausführung, wobei unkompilierte SQL-Konstrukte und andere Objekte empfangen werden, bevor sie in SQL gerendert werden.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params, execution_options):
    "listen for the 'before_execute' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params):
    "listen for the 'before_execute' event"

    # ... (event handling logic) ...

Geändert in Version 1.4: Das Ereignis ConnectionEvents.before_execute() akzeptiert nun die Argumente ConnectionEvents.before_execute.conn, ConnectionEvents.before_execute.clauseelement, ConnectionEvents.before_execute.multiparams, ConnectionEvents.before_execute.params, ConnectionEvents.before_execute.execution_options. Die Unterstützung für Listener-Funktionen, die die oben genannten Argumentsignaturen als „veraltet“ akzeptieren, wird in einer zukünftigen Version entfernt.

Dieses Ereignis ist nützlich für die Fehlersuche bei SQL-Kompilierungsproblemen sowie für die frühe Manipulation der an die Datenbank gesendeten Parameter, da die Parameterlisten hier in einem konsistenten Format vorliegen.

Dieses Ereignis kann optional mit dem Flag retval=True eingerichtet werden. Die Argumente clauseelement, multiparams und params sollten in diesem Fall als Drei-Tupel zurückgegeben werden.

@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
Parameter:

  • conn – Connection -Objekt

  • clauseelement – SQL-Ausdrucks-Konstrukt, Compiled -Instanz oder Zeichenfolgenanweisung, die an Connection.execute() übergeben wurde.

  • multiparams – Mehrere Parametersätze, eine Liste von Dictionaries.

  • params – Einzelner Parametersatz, ein einzelnes Dictionary.

  • execution_options –

    Dictionary der mit dem Statement übergebenen Ausführungsoptionen, falls vorhanden. Dies ist eine Zusammenführung aller zu verwendenden Optionen, einschließlich derer des Statements, der Verbindung und derer, die für den 2.0-Stil der Ausführung selbst an die Methode übergeben wurden.

Siehe auch

before_cursor_execute()

method sqlalchemy.events.ConnectionEvents.begin(conn: Connection) → None

Intercept begin() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin')
def receive_begin(conn):
    "listen for the 'begin' event"

    # ... (event handling logic) ...
Parameter:

conn – Connection -Objekt

method sqlalchemy.events.ConnectionEvents.begin_twophase(conn: Connection, xid: Any) → None

Intercept begin_twophase() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin_twophase')
def receive_begin_twophase(conn, xid):
    "listen for the 'begin_twophase' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection -Objekt

  • xid – Zwei-Phasen-XID-Identifikator

method sqlalchemy.events.ConnectionEvents.commit(conn: Connection) → None

Intercept commit() events, wie sie von einem Transaction ausgelöst werden.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit')
def receive_commit(conn):
    "listen for the 'commit' event"

    # ... (event handling logic) ...

Beachten Sie, dass der Pool eine DBAPI-Verbindung auch beim Einchecken „automatisch committen“ kann, wenn das Flag reset_on_return auf den Wert 'commit' gesetzt ist. Um diesen Commit abzufangen, verwenden Sie den Hook PoolEvents.reset().

Parameter:

conn – Connection -Objekt

method sqlalchemy.events.ConnectionEvents.commit_twophase(conn: Connection, xid: Any, is_prepared: bool) → None

Intercept commit_twophase() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit_twophase')
def receive_commit_twophase(conn, xid, is_prepared):
    "listen for the 'commit_twophase' event"

    # ... (event handling logic) ...
Parameter:
attribute sqlalchemy.events.ConnectionEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.ConnectionEventsDispatch object>

verweist zurück auf die _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

method sqlalchemy.events.ConnectionEvents.engine_connect(conn: Connection) → None

Intercept the creation of a new Connection.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn):
    "listen for the 'engine_connect' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-2.0, will be removed in a future release)
@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn, branch):
    "listen for the 'engine_connect' event"

    # ... (event handling logic) ...

Geändert in Version 2.0: Das Ereignis ConnectionEvents.engine_connect() akzeptiert nun die Argumente ConnectionEvents.engine_connect.conn. Die Unterstützung für Listener-Funktionen, die die oben genannten Argumentsignaturen als „veraltet“ akzeptieren, wird in einer zukünftigen Version entfernt.

Dieses Ereignis wird typischerweise als direktes Ergebnis des Aufrufs der Methode Engine.connect() aufgerufen.

Es unterscheidet sich von der Methode PoolEvents.connect(), die sich auf die tatsächliche Verbindung zu einer Datenbank auf DBAPI-Ebene bezieht; eine DBAPI-Verbindung kann gepoolt und für viele Operationen wiederverwendet werden. Im Gegensatz dazu bezieht sich dieses Ereignis nur auf die Erzeugung eines höherrangigen Connection-Wrappers um eine solche DBAPI-Verbindung.

Es unterscheidet sich auch vom Ereignis PoolEvents.checkout(), da es spezifisch für das Connection-Objekt ist und nicht für die DBAPI-Verbindung, mit der PoolEvents.checkout() arbeitet, obwohl diese DBAPI-Verbindung hier über das Attribut Connection.connection verfügbar ist. Beachten Sie jedoch, dass es tatsächlich mehrere PoolEvents.checkout()-Ereignisse innerhalb der Lebensdauer eines einzelnen Connection-Objekts geben kann, wenn diese Connection ungültig gemacht und neu etabliert wird.

Parameter:

conn – Connection -Objekt.

Siehe auch

PoolEvents.checkout() das untergeordnete Pool-Checkout-Ereignis für eine einzelne DBAPI-Verbindung

method sqlalchemy.events.ConnectionEvents.engine_disposed(engine: Engine) → None

Intercept when the Engine.dispose() method is called.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_disposed')
def receive_engine_disposed(engine):
    "listen for the 'engine_disposed' event"

    # ... (event handling logic) ...

Die Methode Engine.dispose() weist die Engine an, ihren Connection-Pool (z. B. Pool) zu „entsorgen“ und durch einen neuen zu ersetzen. Das Entsorgen des alten Pools hat zur Folge, dass bereits eingecheckte Verbindungen geschlossen werden. Der neue Pool stellt keine neuen Verbindungen her, bis er zum ersten Mal verwendet wird.

Dieses Ereignis kann verwendet werden, um anzuzeigen, dass auch ressourcen im Zusammenhang mit der Engine bereinigt werden sollen. Dabei ist zu beachten, dass die Engine weiterhin für neue Anfragen verwendet werden kann, in welchem Fall sie Verbindung-Ressourcen erneut erwirbt.

method sqlalchemy.events.ConnectionEvents.prepare_twophase(conn: Connection, xid: Any) → None

Intercept prepare_twophase() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'prepare_twophase')
def receive_prepare_twophase(conn, xid):
    "listen for the 'prepare_twophase' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection -Objekt

  • xid – Zwei-Phasen-XID-Identifikator

method sqlalchemy.events.ConnectionEvents.release_savepoint(conn: Connection, name: str, context: None) → None

Intercept release_savepoint() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'release_savepoint')
def receive_release_savepoint(conn, name, context):
    "listen for the 'release_savepoint' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection -Objekt

  • name – verwendeter Name für den Savepoint.

  • context – nicht verwendet

method sqlalchemy.events.ConnectionEvents.rollback(conn: Connection) → None

Intercept rollback() events, wie sie von einem Transaction ausgelöst werden.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback')
def receive_rollback(conn):
    "listen for the 'rollback' event"

    # ... (event handling logic) ...

Beachten Sie, dass der Pool eine DBAPI-Verbindung auch beim Einchecken „automatisch zurückrollt“, wenn das Flag reset_on_return auf seinen Standardwert 'rollback' gesetzt ist. Um diesen Rollback abzufangen, verwenden Sie den Hook PoolEvents.reset().

Parameter:

conn – Connection -Objekt

Siehe auch

PoolEvents.reset()

method sqlalchemy.events.ConnectionEvents.rollback_savepoint(conn: Connection, name: str, context: None) → None

Intercept rollback_savepoint() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_savepoint')
def receive_rollback_savepoint(conn, name, context):
    "listen for the 'rollback_savepoint' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection -Objekt

  • name – verwendeter Name für den Savepoint.

  • context – nicht verwendet

method sqlalchemy.events.ConnectionEvents.rollback_twophase(conn: Connection, xid: Any, is_prepared: bool) → None

Intercept rollback_twophase() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_twophase')
def receive_rollback_twophase(conn, xid, is_prepared):
    "listen for the 'rollback_twophase' event"

    # ... (event handling logic) ...
Parameter:
method sqlalchemy.events.ConnectionEvents.savepoint(conn: Connection, name: str) → None

Intercept savepoint() events.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'savepoint')
def receive_savepoint(conn, name):
    "listen for the 'savepoint' event"

    # ... (event handling logic) ...
Parameter:

  • conn – Connection -Objekt

  • name – verwendeter Name für den Savepoint.

method sqlalchemy.events.ConnectionEvents.set_connection_execution_options(conn: Connection, opts: Dict[str, Any]) → None

Intercept when the Connection.execution_options() method is called.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_connection_execution_options')
def receive_set_connection_execution_options(conn, opts):
    "listen for the 'set_connection_execution_options' event"

    # ... (event handling logic) ...

Diese Methode wird aufgerufen, nachdem die neue Connection mit der neu aktualisierten Sammlung von Ausführungsoptionen erstellt wurde, aber bevor die Dialect diese neuen Optionen verarbeitet hat.

Beachten Sie, dass diese Methode nicht aufgerufen wird, wenn eine neue Connection erstellt wird, die Ausführungsoptionen von ihrer übergeordneten Engine erbt. Um diesen Zustand abzufangen, verwenden Sie das Ereignis ConnectionEvents.engine_connect().

Parameter:

  • conn – Das neu kopierte Connection -Objekt

  • opts –

    Dictionary von Optionen, die an die Methode Connection.execution_options() übergeben wurden. Dieses Dictionary kann direkt geändert werden, um die endgültigen Optionen zu beeinflussen, die wirksam werden.

    Neu in Version 2.0: Das Dictionary opts kann direkt geändert werden.

Siehe auch

ConnectionEvents.set_engine_execution_options() - Ereignis, das aufgerufen wird, wenn Engine.execution_options() aufgerufen wird.

methode sqlalchemy.events.ConnectionEvents.set_engine_execution_options(engine: Engine, opts: Dict[str, Any]) → None

Abfangen, wenn die Methode Engine.execution_options() aufgerufen wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_engine_execution_options')
def receive_set_engine_execution_options(engine, opts):
    "listen for the 'set_engine_execution_options' event"

    # ... (event handling logic) ...

Die Methode Engine.execution_options() erzeugt eine flache Kopie des Engine, die die neuen Optionen speichert. Dieser neue Engine wird hier übergeben. Eine spezielle Anwendung dieser Methode ist das Hinzufügen eines ConnectionEvents.engine_connect()-Ereignis-Handlers zum gegebenen Engine, der eine auf diese Ausführungsoptionen zugeschnittene Aufgabe pro Connection ausführt.

Parameter:

  • conn – Das neu kopierte Engine-Objekt

  • opts –

    Dictionary von Optionen, die an die Methode Connection.execution_options() übergeben wurden. Dieses Dictionary kann direkt geändert werden, um die endgültigen Optionen zu beeinflussen, die wirksam werden.

    Neu in Version 2.0: Das Dictionary opts kann direkt geändert werden.

Siehe auch

ConnectionEvents.set_connection_execution_options() - Ereignis, das aufgerufen wird, wenn Connection.execution_options() aufgerufen wird.

klasse sqlalchemy.events.DialectEvents

Schnittstelle für Ereignisse von Funktionen, die die Ausführung ersetzen.

Diese Ereignisse ermöglichen die direkte Instrumentierung und den Ersatz wichtiger Dialektfunktionen, die mit der DBAPI interagieren.

Hinweis

DialectEvents-Hooks sollten als **semi-öffentlich** und experimentell betrachtet werden. Diese Hooks sind nicht für den allgemeinen Gebrauch bestimmt und nur für Situationen, in denen eine komplexe Neudefinition von DBAPI-Mechanismen in einen bestehenden Dialekt injiziert werden muss. Für Ereignisse zur Abfangen von Anweisungen für den allgemeinen Gebrauch verwenden Sie bitte die ConnectionEvents-Schnittstelle.

Siehe auch

ConnectionEvents.before_cursor_execute()

ConnectionEvents.before_execute()

ConnectionEvents.after_cursor_execute()

ConnectionEvents.after_execute()

Mitglieder

dispatch, do_connect(), do_execute(), do_execute_no_params(), do_executemany(), do_setinputsizes(), handle_error()

Klassensignatur

class sqlalchemy.events.DialectEvents (sqlalchemy.event.Events)

attribut sqlalchemy.events.DialectEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.DialectEventsDispatch object>

verweist zurück auf die _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

methode sqlalchemy.events.DialectEvents.do_connect(dialect: Dialect, conn_rec: ConnectionPoolEntry, cargs: Tuple[Any, ...], cparams: Dict[str, Any]) → DBAPIConnection | None

Verbindungsargumente erhalten, bevor eine Verbindung hergestellt wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_connect')
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    "listen for the 'do_connect' event"

    # ... (event handling logic) ...

Dieses Ereignis ist nützlich, da es dem Handler ermöglicht, die cargs- und/oder cparams-Sammlungen zu manipulieren, die steuern, wie die DBAPI-Funktion connect() aufgerufen wird. cargs ist immer eine Python-Liste, die direkt geändert werden kann, und cparams ist ein Python-Dictionary, das ebenfalls geändert werden kann.

e = create_engine("postgresql+psycopg2://user@host/dbname")


@event.listens_for(e, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    cparams["password"] = "some_password"

Der Ereignis-Hook kann auch verwendet werden, um den Aufruf von connect() vollständig zu überschreiben, indem ein DBAPI-Verbindungsobjekt zurückgegeben wird, das nicht None ist.

e = create_engine("postgresql+psycopg2://user@host/dbname")


@event.listens_for(e, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    return psycopg2.connect(*cargs, **cparams)

Siehe auch

Benutzerdefinierte DBAPI connect() Argumente / on-connect Routinen

methode sqlalchemy.events.DialectEvents.do_execute(cursor: DBAPICursor, statement: str, parameters: _DBAPISingleExecuteParams, context: ExecutionContext) → Literal[True] | None

Erhalten Sie einen Cursor, für den execute() aufgerufen werden soll.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute')
def receive_do_execute(cursor, statement, parameters, context):
    "listen for the 'do_execute' event"

    # ... (event handling logic) ...

Geben Sie den Wert True zurück, um weitere Ereignisse zu stoppen und anzuzeigen, dass die Cursor-Ausführung bereits im Ereignis-Handler stattgefunden hat.

methode sqlalchemy.events.DialectEvents.do_execute_no_params(cursor: DBAPICursor, statement: str, context: ExecutionContext) → Literal[True] | None

Erhalten Sie einen Cursor, für den execute() ohne Parameter aufgerufen werden soll.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute_no_params')
def receive_do_execute_no_params(cursor, statement, context):
    "listen for the 'do_execute_no_params' event"

    # ... (event handling logic) ...

Geben Sie den Wert True zurück, um weitere Ereignisse zu stoppen und anzuzeigen, dass die Cursor-Ausführung bereits im Ereignis-Handler stattgefunden hat.

methode sqlalchemy.events.DialectEvents.do_executemany(cursor: DBAPICursor, statement: str, parameters: _DBAPIMultiExecuteParams, context: ExecutionContext) → Literal[True] | None

Erhalten Sie einen Cursor, für den executemany() aufgerufen werden soll.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_executemany')
def receive_do_executemany(cursor, statement, parameters, context):
    "listen for the 'do_executemany' event"

    # ... (event handling logic) ...

Geben Sie den Wert True zurück, um weitere Ereignisse zu stoppen und anzuzeigen, dass die Cursor-Ausführung bereits im Ereignis-Handler stattgefunden hat.

methode sqlalchemy.events.DialectEvents.do_setinputsizes(inputsizes: Dict[BindParameter[Any], Any], cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext) → None

Das setinputsizes-Dictionary erhalten, um es möglicherweise zu ändern.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_setinputsizes')
def receive_do_setinputsizes(inputsizes, cursor, statement, parameters, context):
    "listen for the 'do_setinputsizes' event"

    # ... (event handling logic) ...

Dieses Ereignis wird ausgelöst, wenn der Dialekt die DBAPI-Methode cursor.setinputsizes() verwendet, die Informationen zur Parameterbindung für eine bestimmte Anweisung übergibt. Das gegebene inputsizes-Dictionary enthält BindParameter-Objekte als Schlüssel, verknüpft mit DBAPI-spezifischen Typobjekten als Werte; für nicht gebundene Parameter werden sie dem Dictionary mit None als Wert hinzugefügt, was bedeutet, dass der Parameter nicht in den endgültigen Aufruf von setinputsizes aufgenommen wird. Das Ereignis kann verwendet werden, um die gebundenen Datentypen zu inspizieren und/oder zu protokollieren sowie um das Dictionary direkt zu ändern. Parameter können zu diesem Dictionary hinzugefügt, geändert oder daraus entfernt werden. Aufrufer möchten normalerweise das Attribut BindParameter.type der gegebenen Bindungsobjekte inspizieren, um Entscheidungen über das DBAPI-Objekt zu treffen.

Nach dem Ereignis wird das inputsizes-Dictionary in eine geeignete Datenstruktur umgewandelt, die an cursor.setinputsizes übergeben wird; entweder eine Liste für einen Positionsbindeparameter-Ausführungsstil oder ein Dictionary von String-Parameternamen zu DBAPI-Typobjekten für einen benannten Bindeparameter-Ausführungsstil.

Der setinputsizes-Hook wird generell nur für Dialekte verwendet, die das Flag use_setinputsizes=True enthalten. Zu den Dialekten, die dies verwenden, gehören die Dialekte python-oracledb, cx_Oracle, pg8000, asyncpg und pyodbc.

Hinweis

Für die Verwendung mit pyodbc muss das Flag use_setinputsizes an den Dialekt übergeben werden, z. B.

create_engine("mssql+pyodbc://...", use_setinputsizes=True)

Siehe auch

Setinputsizes-Unterstützung

Neu in Version 1.2.9.

Siehe auch

Feingranulare Kontrolle über die Performance der cx_Oracle-Datenbindung mit setinputsizes

methode sqlalchemy.events.DialectEvents.handle_error(exception_context: ExceptionContext) → BaseException | None

Alle Ausnahmen abfangen, die vom Dialect verarbeitet werden, typischerweise, aber nicht ausschließlich, solche, die im Geltungsbereich einer Connection ausgelöst werden.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeEngine, 'handle_error')
def receive_handle_error(exception_context):
    "listen for the 'handle_error' event"

    # ... (event handling logic) ...

Geändert in Version 2.0: Das Ereignis DialectEvents.handle_error() wurde in die Klasse DialectEvents verschoben, von der Klasse ConnectionEvents, so dass es auch an der mit dem Parameter create_engine.pool_pre_ping konfigurierten „pre ping“-Operation teilnehmen kann. Das Ereignis bleibt registriert, indem der Engine als Ereignisziel verwendet wird. Beachten Sie jedoch, dass die Verwendung der Connection als Ereignisziel für DialectEvents.handle_error() nicht mehr unterstützt wird.

Dies umfasst alle Ausnahmen, die von der DBAPI sowie im Rahmen der Anweisungsausführung von SQLAlchemy ausgelöst werden, einschließlich Kodierungsfehlern und anderen Fehlern bei der Anweisungsvalidierung. Andere Bereiche, in denen das Ereignis aufgerufen wird, sind Transaktionsbeginn und -ende, Abrufen von Ergebnissätzen, Cursorerstellung.

Beachten Sie, dass handle_error() zu *jeder Zeit* neue Arten von Ausnahmen und neue Aufrufszenarien unterstützen kann. Code, der dieses Ereignis verwendet, muss damit rechnen, dass in kleineren Releases neue Aufrufsmuster vorhanden sind.

Um die große Vielfalt an Mitgliedern, die einer Ausnahme entsprechen, zu unterstützen und die Erweiterbarkeit des Ereignisses ohne Rückwärtskompatibilität zu ermöglichen, ist das einzige Argument eine Instanz von ExceptionContext. Dieses Objekt enthält Datenmember, die Details über die Ausnahme darstellen.

Anwendungsfälle, die von diesem Hook unterstützt werden:

  • Nur-Lese-Ausnahmebehandlung auf niedriger Ebene für Protokollierungs- und Debugging-Zwecke

  • Feststellen, ob eine DBAPI-Verbindungsfehlermeldung anzeigt, dass die Datenbankverbindung wiederhergestellt werden muss, einschließlich für den „pre_ping“-Handler, der von **einigen** Dialekten verwendet wird

  • Feststellen oder Deaktivieren, ob eine Verbindung oder der besitzende Verbindungspool als Reaktion auf eine bestimmte Ausnahme ungültig oder abgelaufen ist

  • Ausnahme-Umschreibung

Der Hook wird aufgerufen, während der Cursor der fehlgeschlagenen Operation (falls vorhanden) noch geöffnet und zugänglich ist. Spezielle Bereinigungsoperationen können für diesen Cursor aufgerufen werden; SQLAlchemy versucht, diesen Cursor nach Aufruf dieses Hooks zu schließen.

Ab SQLAlchemy 2.0 nimmt der „pre_ping“-Handler, der über den Parameter create_engine.pool_pre_ping aktiviert wird, ebenfalls am handle_error()-Prozess teil, **für jene Dialekte, die auf Disconnect-Codes zur Erkennung der Datenbanklebensfähigkeit angewiesen sind**. Beachten Sie, dass einige Dialekte wie psycopg, psycopg2 und die meisten MySQL-Dialekte eine native ping()-Methode der DBAPI verwenden, die keine Disconnect-Codes nutzt.

Geändert in Version 2.0.0: Der Ereignis-Hook DialectEvents.handle_error() beteiligt sich an „pre-ping“-Operationen von Verbindungspools. Innerhalb dieser Verwendung ist das Attribut ExceptionContext.engine None, jedoch ist der verwendete Dialect immer über das Attribut ExceptionContext.dialect verfügbar.

Geändert in Version 2.0.5: Attribut ExceptionContext.is_pre_ping hinzugefügt, das auf True gesetzt wird, wenn der Ereignis-Hook DialectEvents.handle_error() innerhalb einer Verbindungspool-Pre-Ping-Operation ausgelöst wird.

Geändert in Version 2.0.5: Ein Problem wurde behoben, das es den PostgreSQL-Treibern psycopg und psycopg2 sowie allen MySQL-Treibern ermöglicht, ordnungsgemäß am Ereignis-Hook DialectEvents.handle_error() während Verbindungspool-„Pre-Ping“-Operationen teilzunehmen; zuvor war die Implementierung für diese Treiber nicht funktionsfähig.

Eine Handler-Funktion hat zwei Möglichkeiten, die von SQLAlchemy konstruierte Ausnahme durch eine benutzereigene zu ersetzen. Sie kann entweder diese neue Ausnahme direkt auslösen, in diesem Fall werden alle weiteren Ereignis-Listener umgangen und die Ausnahme wird nach entsprechender Bereinigung ausgelöst.

@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")

Warnung

Da das Ereignis DialectEvents.handle_error() speziell vorsieht, dass Ausnahmen als ultimative Ausnahme der fehlgeschlagenen Anweisung neu ausgelöst werden, **werden Stack-Traces irreführend sein**, wenn der benutzereigene Ereignis-Handler selbst fehlschlägt und eine unerwartete Ausnahme auslöst; der Stack-Trace zeigt möglicherweise nicht die tatsächliche Codezeile an, die fehlgeschlagen ist! Es wird empfohlen, hier vorsichtig zu codieren und Protokollierung und/oder Inline-Debugging zu verwenden, wenn unerwartete Ausnahmen auftreten.

Alternativ kann ein „verketteter“ Stil der Ereignisbehandlung verwendet werden, indem der Handler mit dem Modifier retval=True konfiguriert und die neue Ausnahmeinstanz aus der Funktion zurückgegeben wird. In diesem Fall wird die Ereignisbehandlung zum nächsten Handler fortgesetzt. Die „verkettete“ Ausnahme ist über ExceptionContext.chained_exception verfügbar.

@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
        )

Handler, die None zurückgeben, können innerhalb der Kette verwendet werden; wenn ein Handler None zurückgibt, wird die vorherige Ausnahmeinstanz, falls vorhanden, als aktuelle Ausnahme beibehalten, die an den nächsten Handler weitergegeben wird.

Wenn eine benutzerdefinierte Ausnahme ausgelöst oder zurückgegeben wird, löst SQLAlchemy diese neue Ausnahme unverändert aus, sie wird nicht von einem SQLAlchemy-Objekt umschlossen. Wenn die Ausnahme keine Unterklasse von sqlalchemy.exc.StatementError ist, sind möglicherweise bestimmte Funktionen nicht verfügbar; derzeit gehört dazu die ORM-Funktion, die dem autoflush-Prozess innerhalb von Ausnahmen, die während des autoflush auftreten, einen Detailhinweis hinzufügt.

Parameter:

context – ein ExceptionContext-Objekt. Details zu allen verfügbaren Mitgliedern finden Sie in dieser Klasse.

Siehe auch

Unterstützung neuer Datenbankfehlercodes für Disconnect-Szenarien

Schema-Ereignisse

Objektname Beschreibung

DDLEvents

Definieren Sie Ereignis-Listener für Schema-Objekte, d.h. SchemaItem und andere Unterklassen von SchemaEventTarget, einschließlich MetaData, Table, Column usw.

SchemaEventTarget

Basisklasse für Elemente, die Ziele von DDLEvents-Ereignissen sind.
klasse sqlalchemy.events.DDLEvents

Definieren Sie Ereignis-Listener für Schema-Objekte, d.h. SchemaItem und andere Unterklassen von SchemaEventTarget, einschließlich MetaData, Table, Column usw.

CREATE / DROP Events

Ereignisse, die ausgelöst werden, wenn CREATE- und DROP-Befehle an die Datenbank gesendet werden. Die Ereignis-Hooks in dieser Kategorie umfassen DDLEvents.before_create(), DDLEvents.after_create(), DDLEvents.before_drop() und DDLEvents.after_drop().

Diese Events werden beim Verwenden von schemaweiten Methoden wie MetaData.create_all() und MetaData.drop_all() ausgelöst. Pro-Objekt-Create/Drop-Methoden wie Table.create(), Table.drop(), Index.create() sind ebenfalls enthalten, ebenso wie dialektspezifische Methoden wie ENUM.create().

Neu in Version 2.0: DDLEvents Event-Hooks finden jetzt auch für Nicht-Tabellen-Objekte statt, einschließlich Constraints, Indizes und dialektspezifischer Schematypen.

Event-Hooks können direkt an ein Table-Objekt oder an eine MetaData-Sammlung angehängt werden, sowie an jede SchemaItem-Klasse oder jedes Objekt, das individuell mit einem eigenen SQL-Befehl erstellt und gelöscht werden kann. Solche Klassen umfassen Index, Sequence und dialektspezifische Klassen wie ENUM.

Beispiel für die Verwendung des DDLEvents.after_create() Events, bei dem ein benutzerdefinierter Event-Hook einen ALTER TABLE Befehl über die aktuelle Verbindung ausgibt, nachdem der CREATE TABLE Befehl ausgegeben wurde.

from sqlalchemy import create_engine
from sqlalchemy import event
from sqlalchemy import Table, Column, Metadata, Integer

m = MetaData()
some_table = Table("some_table", m, Column("data", Integer))


@event.listens_for(some_table, "after_create")
def after_create(target, connection, **kw):
    connection.execute(
        text("ALTER TABLE %s SET name=foo_%s" % (target.name, target.name))
    )


some_engine = create_engine("postgresql://scott:tiger@host/test")

# will emit "CREATE TABLE some_table" as well as the above
# "ALTER TABLE" statement afterwards
m.create_all(some_engine)

Constraint-Objekte wie ForeignKeyConstraint, UniqueConstraint, CheckConstraint können ebenfalls für diese Events abonniert werden, jedoch werden sie nicht normalerweise Events auslösen, da diese Objekte üblicherweise inline innerhalb einer umgebenden CREATE TABLE-Anweisung gerendert und implizit aus einer DROP TABLE-Anweisung gelöscht werden.

Für das Index-Konstrukt wird der Event-Hook für CREATE INDEX ausgelöst, jedoch gibt SQLAlchemy normalerweise kein DROP INDEX beim Löschen von Tabellen aus, da dies wiederum implizit innerhalb der DROP TABLE-Anweisung geschieht.

Neu in Version 2.0: Die Unterstützung für SchemaItem-Objekte für Create/Drop-Events wurde von der bisherigen Unterstützung für MetaData und Table erweitert, um auch Constraint und alle Unterklassen, Index, Sequence und einige typspezifische Konstrukte wie ENUM einzuschließen.

Hinweis

Diese Event-Hooks werden nur im Geltungsbereich von SQLAlchemys Create/Drop-Methoden ausgelöst; sie werden nicht notwendigerweise von Tools wie alembic unterstützt.

Attachment Events

Attachment-Events werden bereitgestellt, um das Verhalten anzupassen, wenn ein untergeordnetes Schemaelement mit einem übergeordneten Element verknüpft wird, z. B. wenn eine Column mit ihrer Table verknüpft wird, wenn eine ForeignKeyConstraint mit einer Table verknüpft wird, usw. Diese Events umfassen DDLEvents.before_parent_attach() und DDLEvents.after_parent_attach().

Reflection Events

Das Event DDLEvents.column_reflect() wird verwendet, um die In-Python-Definition von Datenbankspalten abzufangen und zu modifizieren, wenn die Reflection von Datenbanktabellen durchgeführt wird.

Verwendung mit generischem DDL

DDL-Events integrieren sich eng mit der DDL-Klasse und der ExecutableDDLElement-Hierarchie von DDL-Klauselkonstrukten, die selbst als Listener-Callables geeignet sind.

from sqlalchemy import DDL

event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
)

Event-Weitergabe an MetaData-Kopien

Für alle DDLEvent-Events stellt das Schlüsselwortargument propagate=True sicher, dass ein bestimmter Event-Handler an Kopien des Objekts weitergegeben wird, die bei der Verwendung der Methode Table.to_metadata() erstellt werden.

from sqlalchemy import DDL

metadata = MetaData()
some_table = Table("some_table", metadata, Column("data", Integer))

event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
    propagate=True,
)

new_metadata = MetaData()
new_table = some_table.to_metadata(new_metadata)

Das obige DDL-Objekt wird mit dem Event DDLEvents.after_create() sowohl für die some_table als auch für die new_table Table-Objekte verknüpft.

Siehe auch

Events

ExecutableDDLElement

DDL

Steuern von DDL-Sequenzen

Mitglieder

after_create(), after_drop(), after_parent_attach(), before_create(), before_drop(), before_parent_attach(), column_reflect(), dispatch

Klassensignatur

class sqlalchemy.events.DDLEvents (sqlalchemy.event.Events)

method sqlalchemy.events.DDLEvents.after_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

Wird nach der Ausgabe von CREATE-Anweisungen aufgerufen.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_create')
def receive_after_create(target, connection, **kw):
    "listen for the 'after_create' event"

    # ... (event handling logic) ...
Parameter:

  • target –

    das SchemaObject, z. B. eine MetaData oder Table, aber auch alle Create/Drop-Objekte wie Index, Sequence usw., das Ziel des Events ist.

    Neu in Version 2.0: Unterstützung für alle SchemaItem-Objekte hinzugefügt.

  • connection – die Connection, über die die CREATE-Anweisung oder -Anweisungen ausgegeben wurden.

  • **kw – zusätzliche Schlüsselwortargumente, die für das Event relevant sind. Der Inhalt dieses Wörterbuchs kann sich zwischen den Versionen ändern und umfasst die Liste der Tabellen, die für ein metadatenebene Event generiert werden, das checkfirst-Flag und andere Elemente, die von internen Events verwendet werden.

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

method sqlalchemy.events.DDLEvents.after_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

Wird nach der Ausgabe von DROP-Anweisungen aufgerufen.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_drop')
def receive_after_drop(target, connection, **kw):
    "listen for the 'after_drop' event"

    # ... (event handling logic) ...
Parameter:

  • target –

    das SchemaObject, z. B. eine MetaData oder Table, aber auch alle Create/Drop-Objekte wie Index, Sequence usw., das Ziel des Events ist.

    Neu in Version 2.0: Unterstützung für alle SchemaItem-Objekte hinzugefügt.

  • connection – die Connection, über die die DROP-Anweisung oder -Anweisungen ausgegeben wurden.

  • **kw – zusätzliche Schlüsselwortargumente, die für das Event relevant sind. Der Inhalt dieses Wörterbuchs kann sich zwischen den Versionen ändern und umfasst die Liste der Tabellen, die für ein metadatenebene Event generiert werden, das checkfirst-Flag und andere Elemente, die von internen Events verwendet werden.

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

method sqlalchemy.events.DDLEvents.after_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None

Wird aufgerufen, nachdem ein SchemaItem mit einem übergeordneten SchemaItem verknüpft wurde.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_parent_attach')
def receive_after_parent_attach(target, parent):
    "listen for the 'after_parent_attach' event"

    # ... (event handling logic) ...
Parameter:

  • target – das Zielobjekt

  • parent – das übergeordnete Objekt, an das das Ziel angehängt wird.

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

method sqlalchemy.events.DDLEvents.before_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

Wird vor der Ausgabe von CREATE-Anweisungen aufgerufen.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_create')
def receive_before_create(target, connection, **kw):
    "listen for the 'before_create' event"

    # ... (event handling logic) ...
Parameter:

  • target –

    das SchemaObject, z. B. eine MetaData oder Table, aber auch alle Create/Drop-Objekte wie Index, Sequence usw., das Ziel des Events ist.

    Neu in Version 2.0: Unterstützung für alle SchemaItem-Objekte hinzugefügt.

  • connection – die Connection, über die die CREATE-Anweisung oder -Anweisungen ausgegeben werden.

  • **kw – zusätzliche Schlüsselwortargumente, die für das Event relevant sind. Der Inhalt dieses Wörterbuchs kann sich zwischen den Versionen ändern und umfasst die Liste der Tabellen, die für ein metadatenebene Event generiert werden, das checkfirst-Flag und andere Elemente, die von internen Events verwendet werden.

listen() akzeptiert den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

listen() akzeptiert den Modifikator insert=True für dieses Event; wenn True, wird die Listener-Funktion vor die interne Liste der Events bei deren Entdeckung gestellt und wird vor registrierten Listener-Funktionen ausgeführt, die dieses Argument nicht übergeben.

method sqlalchemy.events.DDLEvents.before_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

Wird vor der Ausgabe von DROP-Anweisungen aufgerufen.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_drop')
def receive_before_drop(target, connection, **kw):
    "listen for the 'before_drop' event"

    # ... (event handling logic) ...
Parameter:

  • target –

    das SchemaObject, z. B. eine MetaData oder Table, aber auch alle Create/Drop-Objekte wie Index, Sequence usw., das Ziel des Events ist.

    Neu in Version 2.0: Unterstützung für alle SchemaItem-Objekte hinzugefügt.

  • connection – die Connection, über die die DROP-Anweisung oder -Anweisungen ausgegeben werden.

  • **kw – zusätzliche Schlüsselwortargumente, die für das Event relevant sind. Der Inhalt dieses Wörterbuchs kann sich zwischen den Versionen ändern und umfasst die Liste der Tabellen, die für ein metadatenebene Event generiert werden, das checkfirst-Flag und andere Elemente, die von internen Events verwendet werden.

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

method sqlalchemy.events.DDLEvents.before_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None

Wird aufgerufen, bevor ein SchemaItem mit einem übergeordneten SchemaItem verknüpft wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_parent_attach')
def receive_before_parent_attach(target, parent):
    "listen for the 'before_parent_attach' event"

    # ... (event handling logic) ...
Parameter:

  • target – das Zielobjekt

  • parent – das übergeordnete Objekt, an das das Ziel angehängt wird.

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

method sqlalchemy.events.DDLEvents.column_reflect(inspector: Inspector, table: Table, column_info: ReflectedColumn) → None

Wird für jede Einheit von "Spalteninformationen" aufgerufen, die beim Reflektieren einer Table abgerufen wird.

Beispielhafte Argumentübergaben

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'column_reflect')
def receive_column_reflect(inspector, table, column_info):
    "listen for the 'column_reflect' event"

    # ... (event handling logic) ...

Dieses Event wird am einfachsten verwendet, indem es auf eine bestimmte MetaData-Instanz angewendet wird, wo es für alle Table-Objekte innerhalb dieser MetaData gilt, die reflektiert werden.

metadata = MetaData()


@event.listens_for(metadata, "column_reflect")
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected
    # under this MetaData
    ...


# will use the above event hook
my_table = Table("my_table", metadata, autoload_with=some_engine)

Neu in Version 1.4.0b2: Der Hook DDLEvents.column_reflect() kann jetzt auch auf ein MetaData-Objekt angewendet werden, sowie auf die MetaData-Klasse selbst, wo es für alle Table-Objekte gilt, die mit der Ziel- MetaData verknüpft sind.

Es kann auch auf die Table-Klasse allgemein angewendet werden.

from sqlalchemy import Table


@event.listens_for(Table, "column_reflect")
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected
    ...

Es kann auch auf eine bestimmte Table zum Zeitpunkt der Reflexion angewendet werden, indem der Parameter Table.listeners verwendet wird.

t1 = Table(
    "my_table",
    autoload_with=some_engine,
    listeners=[("column_reflect", receive_column_reflect)],
)

Das Wörterbuch mit Spalteninformationen, wie es vom Dialekt zurückgegeben wird, wird übergeben und kann modifiziert werden. Das Wörterbuch ist das, das in jedem Element der Liste zurückgegeben wird, die von Inspector.get_columns() zurückgegeben wird.

  • name - der Name der Spalte, wird auf den Parameter Column.name angewendet.

  • type - der Typ dieser Spalte, der eine Instanz von TypeEngine sein sollte, wird auf den Parameter Column.type angewendet

  • nullable - boolesches Flag, ob die Spalte NULL oder NOT NULL ist, wird auf den Parameter Column.nullable angewendet

  • default - der Standardwert der Spalte auf dem Server. Dies wird normalerweise als einfacher String-SQL-Ausdruck angegeben, jedoch kann das Ereignis auch ein FetchedValue-, DefaultClause- oder text()-Objekt übergeben. Wird auf den Parameter Column.server_default angewendet

Das Ereignis wird aufgerufen, bevor eine Aktion gegen dieses Wörterbuch ausgeführt wird, und der Inhalt kann geändert werden; die folgenden zusätzlichen Schlüssel können dem Wörterbuch hinzugefügt werden, um zu ändern, wie die Column weiter konstruiert wird

listen() akzeptiert auch den Modifikator propagate=True für dieses Event; wenn True, wird die Listener-Funktion für alle Kopien des Zielobjekts eingerichtet, d.h. für Kopien, die bei der Verwendung von Table.to_metadata() generiert werden.

Siehe auch

Automatisierung von Spaltenbenennungsschemata aus reflektierten Tabellen - in der ORM-Mapping-Dokumentation

Abfangen von Spaltendefinitionen - in der Automap-Dokumentation

Reflektieren mit Datenbank-agnostischen Typen - in der Reflektieren von Datenbankobjekten-Dokumentation

attribute sqlalchemy.events.DDLEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.DDLEventsDispatch object>

verweist zurück auf die _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

class sqlalchemy.events.SchemaEventTarget

Basisklasse für Elemente, die Ziele von DDLEvents-Ereignissen sind.

Dies schließt SchemaItem sowie SchemaType ein.

Klassensignatur

class sqlalchemy.events.SchemaEventTarget (sqlalchemy.event.registry.EventTarget)