ORM Events¶

Session Events¶

The most basic event hooks are available at the level of the 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 Session.execute() method using the 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 Mapper objects, which are the central configurational object that maps a user-defined class to a Table object. Types of things which occur at the Mapper level include:

• Per-object persistence operations - the most popular mapper hooks are the unit-of-work hooks such as MapperEvents.before_insert(), MapperEvents.after_update(), etc. These events are contrasted to the more coarse grained session-level events such as 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 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 MapperEvents.instrument_class(), MapperEvents.before_mapper_configured() and MapperEvents.mapper_configured() at the individual Mapper level, and MapperEvents.before_configured() and MapperEvents.after_configured() at the level of collections of 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.

Query Events¶

Instrumentation Events¶