ORM Events — SQLAlchemy 2.0.0b1 documentation

ORM Events

The ORM includes a wide variety of hooks available for subscription.

For an introduction to the most commonly used ORM events, see the section Tracking queries, object and Session Changes with Events. The event system in general is discussed at Events. Non-ORM events such as those regarding connections and low-level statement execution are described in Core Events.

Session Events

The most basic event hooks are available at the level of the ORM _orm.Session object. The types of things that are intercepted here include:

• Persistence Operations - the ORM flush process that sends changes to the database can be extended using events that fire off at different parts of the flush, to augment or modify the data being sent to the database or to allow other things to happen when persistence occurs. Read more about persistence events at Persistence Events.
• Object lifecycle events - hooks when objects are added, persisted, deleted from sessions. Read more about these at Object Lifecycle Events.
• Execution Events - Part of the 2.0 style execution model, all SELECT statements against ORM entities emitted, as well as bulk UPDATE and DELETE statements outside of the flush process, are intercepted from the _orm.Session.execute() method using the _orm.SessionEvents.do_orm_execute() method. Read more about this event at Execute Events.

Be sure to read the Tracking queries, object and Session Changes with Events chapter for context on these events.

Mapper Events

Mapper event hooks encompass things that happen as related to individual or multiple _orm.Mapper objects, which are the central configurational object that maps a user-defined class to a _schema.Table object. Types of things which occur at the _orm.Mapper level include:

• Per-object persistence operations - the most popular mapper hooks are the unit-of-work hooks such as _orm.MapperEvents.before_insert(), _orm.MapperEvents.after_update(), etc. These events are contrasted to the more coarse grained session-level events such as _orm.SessionEvents.before_flush() in that they occur within the flush process on a per-object basis; while finer grained activity on an object is more straightforward, availability of _orm.Session features is limited.
• Mapper configuration events - the other major class of mapper hooks are those which occur as a class is mapped, as a mapper is finalized, and when sets of mappers are configured to refer to each other. These events include _orm.MapperEvents.instrument_class(), _orm.MapperEvents.before_mapper_configured() and _orm.MapperEvents.mapper_configured() at the individual _orm.Mapper level, and _orm.MapperEvents.before_configured() and _orm.MapperEvents.after_configured() at the level of collections of _orm.Mapper objects.

Instance Events

Instance events are focused on the construction of ORM mapped instances, including when they are instantiated as transient objects, when they are loaded from the database and become persistent objects, as well as when database refresh or expiration operations occur on the object.

Attribute Events

Attribute events are triggered as things occur on individual attributes of ORM mapped objects. These events form the basis for things like custom validation functions as well as backref handlers.

See also

Changing Attribute Behavior