sqlalchemy.sql.events.DDLEvents

class documentation

class DDLEvents(event.Events):

Define event listeners for schema objects, that is, .SchemaItem and other .SchemaEventTarget subclasses, including _schema.MetaData, _schema.Table, _schema.Column.

_schema.MetaData and _schema.Table support events specifically regarding when CREATE and DROP DDL is emitted to the database.

Attachment events are also provided to customize behavior whenever a child schema element is associated with a parent, such as, when a _schema.Column is associated with its _schema.Table, when a _schema.ForeignKeyConstraint is associated with a _schema.Table, etc.

Example using the after_create event:

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

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

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

event.listen(some_table, "after_create", after_create)

DDL events integrate closely with the .DDL class and the .DDLElement hierarchy of DDL clause constructs, which are themselves appropriate as listener callables:

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

The methods here define the name of an event as well as the names of members that are passed to listener functions.

For all .DDLEvent events, the propagate=True keyword argument will ensure that a given event handler is propagated to copies of the object, which are made when using the _schema.Table.to_metadata method:

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

new_table = some_table.to_metadata(new_metadata)

The above .DDL object will also be associated with the _schema.Table object represented by new_table.

See Also

:ref:`event_toplevel`

.DDLElement

.DDL

:ref:`schema_ddl_sequences`

Method	`_sa_event_column_added_to_pk_constraint`	internal event hook used for primary key naming convention updates.
Method	`after_create`	Called after CREATE statements are emitted.
Method	`after_drop`	Called after DROP statements are emitted.
Method	`after_parent_attach`	Called after a `.SchemaItem` is associated with a parent `.SchemaItem`.
Method	`before_create`	Called before CREATE statements are emitted.
Method	`before_drop`	Called before DROP statements are emitted.
Method	`before_parent_attach`	Called before a `.SchemaItem` is associated with a parent `.SchemaItem`.
Method	`column_reflect`	Called for each unit of 'column info' retrieved when a `_schema.Table` is being reflected.
Class Variable	`_target_class_doc`	Undocumented

Inherited from Events:

Class Method	`_accept_with`	Undocumented
Class Method	`_clear`	Undocumented
Class Method	`_listen`	Undocumented
Class Method	`_remove`	Undocumented
Static Method	`_set_dispatch`	Undocumented

def _sa_event_column_added_to_pk_constraint(self, const, col):

internal event hook used for primary key naming convention updates.

def after_create(self, target, connection, **kw):

Called after CREATE statements are emitted.

.event.listen also accepts the propagate=True modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when _schema.Table.to_metadata is used.

Parameters
target	the `_schema.MetaData` or `_schema.Table` object which is the target of the event.
connection	the `_engine.Connection` where the CREATE statement or statements have been emitted.
**kw	additional keyword arguments relevant to the event. The contents of this dictionary may vary across releases, and include the list of tables being generated for a metadata-level event, the checkfirst flag, and other elements used by internal events.

def after_drop(self, target, connection, **kw):

Called after DROP statements are emitted.

Parameters
target	the `_schema.MetaData` or `_schema.Table` object which is the target of the event.
connection	the `_engine.Connection` where the DROP statement or statements have been emitted.
**kw	additional keyword arguments relevant to the event. The contents of this dictionary may vary across releases, and include the list of tables being generated for a metadata-level event, the checkfirst flag, and other elements used by internal events.

def after_parent_attach(self, target, parent):

Called after a .SchemaItem is associated with a parent .SchemaItem.

Parameters
target	the target object
parent	the parent to which the target is being attached.

def before_create(self, target, connection, **kw):

Called before CREATE statements are emitted.

.event.listen accepts the propagate=True modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when _schema.Table.to_metadata is used.

.event.listen accepts the insert=True modifier for this event; when True, the listener function will be prepended to the internal list of events upon discovery, and execute before registered listener functions that do not pass this argument.

Parameters
target	the `_schema.MetaData` or `_schema.Table` object which is the target of the event.
connection	the `_engine.Connection` where the CREATE statement or statements will be emitted.
**kw	additional keyword arguments relevant to the event. The contents of this dictionary may vary across releases, and include the list of tables being generated for a metadata-level event, the checkfirst flag, and other elements used by internal events.

def before_drop(self, target, connection, **kw):

Called before DROP statements are emitted.

Parameters
target	the `_schema.MetaData` or `_schema.Table` object which is the target of the event.
connection	the `_engine.Connection` where the DROP statement or statements will be emitted.
**kw	additional keyword arguments relevant to the event. The contents of this dictionary may vary across releases, and include the list of tables being generated for a metadata-level event, the checkfirst flag, and other elements used by internal events.

def before_parent_attach(self, target, parent):

Called before a .SchemaItem is associated with a parent .SchemaItem.

Parameters
target	the target object
parent	the parent to which the target is being attached.

def column_reflect(self, inspector, table, column_info):

Called for each unit of 'column info' retrieved when a _schema.Table is being reflected.

This event is most easily used by applying it to a specific _schema.MetaData instance, where it will take effect for all _schema.Table objects within that _schema.MetaData that undergo reflection:

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)

New in version 1.4.0b2: The _events.DDLEvents.column_reflect hook may now be applied to a _schema.MetaData object as well as the _schema.MetaData class itself where it will take place for all _schema.Table objects associated with the targeted _schema.MetaData.

It may also be applied to the _schema.Table class across the board:

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

It can also be applied to a specific _schema.Table at the point that one is being reflected using the :paramref:`_schema.Table.listeners` parameter:

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

A future release will allow it to be associated with a specific _schema.MetaData object as well.

The dictionary of column information as returned by the dialect is passed, and can be modified. The dictionary is that returned in each element of the list returned by .reflection.Inspector.get_columns:

name - the column's name, is applied to the :paramref:`_schema.Column.name` parameter

type - the type of this column, which should be an instance of ~sqlalchemy.types.TypeEngine, is applied to the :paramref:`_schema.Column.type` parameter

nullable - boolean flag if the column is NULL or NOT NULL, is applied to the :paramref:`_schema.Column.nullable` parameter

default - the column's server default value. This is normally specified as a plain string SQL expression, however the event can pass a .FetchedValue, .DefaultClause, or _expression.text object as well. Is applied to the :paramref:`_schema.Column.server_default` parameter

The event is called before any action is taken against this dictionary, and the contents can be modified; the following additional keys may be added to the dictionary to further modify how the _schema.Column is constructed:

key - the string key that will be used to access this _schema.Column in the .c collection; will be applied to the :paramref:`_schema.Column.key` parameter. Is also used for ORM mapping. See the section :ref:`mapper_automated_reflection_schemes` for an example.

quote - force or un-force quoting on the column name; is applied to the :paramref:`_schema.Column.quote` parameter.

info - a dictionary of arbitrary data to follow along with the _schema.Column, is applied to the :paramref:`_schema.Column.info` parameter.