Каскады¶

Поведение каскада сохранения-обновления с двунаправленными отношениями¶

Каскад save-update происходит однонаправленно в контексте двунаправленного отношения, т.е. при использовании параметров relationship.back_populates или relationship.backref для создания двух отдельных объектов relationship(), которые ссылаются друг на друга.

Объект, не связанный с Session, при назначении атрибута или коллекции на родительский объект, связанный с Session, будет автоматически добавлен в тот же Session. Однако та же операция в обратном направлении не будет иметь такого эффекта; объект, не ассоциированный с Session, на который назначен дочерний объект, ассоциированный с Session, не приведет к автоматическому добавлению этого родительского объекта к Session. В целом такое поведение известно как «каскадные обратные ссылки» и представляет собой изменение в поведении, которое было стандартизировано начиная с SQLAlchemy 2.0.

В качестве примера можно привести отображение объектов Order, которые двунаправленно связаны с серией объектов Item через отношения Order.items и Item.order:

mapper_registry.map_imperatively(
    Order,
    order_table,
    properties={"items": relationship(Item, back_populates="order")},
)

mapper_registry.map_imperatively(
    Item,
    item_table,
    properties={"order": relationship(Order, back_populates="items")},
)

Если Order уже связан с Session, а затем создается объект Item и добавляется в коллекцию Order.items этого Order, то Item будет автоматически каскадирован в тот же Session:

>>> o1 = Order()
>>> session.add(o1)
>>> o1 in session
True

>>> i1 = Item()
>>> o1.items.append(i1)
>>> o1 is i1.order
True
>>> i1 in session
True

Выше, двунаправленная природа Order.items и Item.order означает, что добавление к Order.items также присваивает к Item.order. В то же время, каскад save-update позволял объекту Item добавляться к тому же Session, с которым уже был связан родительский Order.

Однако, если описанная выше операция выполняется в обратном направлении, где Item.order присваивается, а не добавляется непосредственно к Order.item, операция каскада в Session не произойдет автоматически, хотя присвоения объектов Order.items и Item.order будут в том же состоянии, что и в предыдущем примере:

>>> o1 = Order()
>>> session.add(o1)
>>> o1 in session
True

>>> i1 = Item()
>>> i1.order = o1
>>> i1 in order.items
True
>>> i1 in session
False

В приведенном выше случае, после создания объекта Item и установки для него всех необходимых состояний, он должен быть добавлен в Session явно:

>>> session.add(i1)

В старых версиях SQLAlchemy каскад сохранения-обновления происходил двунаправленно во всех случаях. Затем он был сделан необязательным с помощью опции, известной как cascade_backrefs. Наконец, в SQLAlchemy 1.4 старое поведение было отменено, а опция cascade_backrefs была удалена в SQLAlchemy 2.0. Это объясняется тем, что пользователи обычно не считают интуитивно понятным, что присвоение атрибута объекту, показанное выше как присвоение i1.order = o1, изменит состояние персистентности этого объекта i1 таким образом, что он теперь находится в состоянии ожидания Session, и часто будут возникать последующие проблемы, когда autoflush будет преждевременно очищать объект и вызывать ошибки в тех случаях, когда данный объект все еще создается и не находится в состоянии готовности к очистке. Также была удалена возможность выбора между однонаправленным и двунаправленным поведением, поскольку эта опция создавала два немного разных способа работы, что увеличивало общую кривую обучения ORM, а также нагрузку на документацию и поддержку пользователей.

Использование каскада удаления с отношениями «многие-ко-многим¶

Опция cascade="all, delete" одинаково хорошо работает с отношениями «многие-ко-многим», в которых используется relationship.secondary для указания таблицы ассоциаций. Когда родительский объект удаляется и, следовательно, деассоциируется со связанными с ним объектами, рабочий процесс обычно удаляет строки из таблицы ассоциаций, но оставляет связанные объекты нетронутыми. В сочетании с cascade="all, delete" дополнительные операторы DELETE будут выполняться для самих дочерних строк.

Следующий пример адаптирует пример Многие ко многим для иллюстрации установки cascade="all, delete" на одной стороне ассоциации:

association_table = Table(
    "association",
    Base.metadata,
    Column("left_id", Integer, ForeignKey("left.id")),
    Column("right_id", Integer, ForeignKey("right.id")),
)


class Parent(Base):
    __tablename__ = "left"
    id = mapped_column(Integer, primary_key=True)
    children = relationship(
        "Child",
        secondary=association_table,
        back_populates="parents",
        cascade="all, delete",
    )


class Child(Base):
    __tablename__ = "right"
    id = mapped_column(Integer, primary_key=True)
    parents = relationship(
        "Parent",
        secondary=association_table,
        back_populates="children",
    )

Выше, когда объект Parent помечается для удаления с помощью Session.delete(), процесс flush, как обычно, удалит связанные строки из таблицы association, однако по правилам каскада он также удалит все связанные строки Child.

Использование каскада внешних ключей ON DELETE с отношениями ORM¶

Поведение каскада «удаления» SQLAlchemy пересекается с функцией ON DELETE ограничения базы данных FOREIGN KEY. SQLAlchemy позволяет конфигурировать это поведение на уровне схемы DDL с помощью конструкций ForeignKey и ForeignKeyConstraint; использование этих объектов в сочетании с метаданными Table описано в ON UPDATE и ON DELETE.

Чтобы использовать каскады внешних ключей ON DELETE в сочетании с relationship(), важно отметить, что параметр relationship.cascade должен быть настроен в соответствии с желаемым поведением «удалить» или «установить нуль» (используя каскад delete или оставляя его опущенным), Таким образом, независимо от того, будет ли ORM или ограничения на уровне базы данных выполнять задачу фактического изменения данных в базе данных, ORM все равно сможет надлежащим образом отслеживать состояние локально присутствующих объектов, которые могут быть затронуты.

Существует дополнительный параметр relationship(), который указывает, в какой степени ORM должен сам пытаться выполнять операции DELETE/UPDATE для связанных строк, а в какой степени он должен полагаться на то, что каскад ограничений FOREIGN KEY со стороны базы данных справится с этой задачей; это параметр relationship.passive_deletes, и он принимает варианты False (по умолчанию), True и "all".

Наиболее типичный пример - когда дочерние строки должны удаляться при удалении родительских строк, и что ON DELETE CASCADE также настроено на соответствующее ограничение FOREIGN KEY:

class Parent(Base):
    __tablename__ = "parent"
    id = mapped_column(Integer, primary_key=True)
    children = relationship(
        "Child",
        back_populates="parent",
        cascade="all, delete",
        passive_deletes=True,
    )


class Child(Base):
    __tablename__ = "child"
    id = mapped_column(Integer, primary_key=True)
    parent_id = mapped_column(Integer, ForeignKey("parent.id", ondelete="CASCADE"))
    parent = relationship("Parent", back_populates="children")

Поведение приведенной выше конфигурации при удалении родительской строки выглядит следующим образом:

1. Приложение вызывает session.delete(my_parent), где my_parent является экземпляром Parent.

2. Когда Session в следующий раз передает изменения в базу данных, все текущие загруженные элементы в коллекции my_parent.children удаляются ORM, то есть для каждой записи выдается оператор DELETE.

3. Если коллекция my_parent.children является выгруженной, то никаких утверждений DELETE не выдается. Если бы флаг relationship.passive_deletes был не установлен для этой коллекции relationship(), то было бы выдано утверждение SELECT для выгруженных объектов Child.

4. Затем выдается оператор DELETE для самой строки my_parent.

5. Настройка ON DELETE CASCADE на уровне базы данных гарантирует, что все строки в child, которые ссылаются на затронутую строку в parent, также будут удалены.

6. Экземпляр Parent, на который ссылается my_parent, а также все экземпляры Child, которые были связаны с этим объектом и были загружены (т.е. произошел шаг 2 выше), деассоциируются от Session.

Использование внешнего ключа ON DELETE в отношениях «многие-ко-многим¶

Как описано в Использование каскада удаления с отношениями «многие-ко-многим, каскад «удаления» работает и для отношений «многие-ко-многим». Чтобы использовать внешние ключи ON DELETE CASCADE в сочетании с отношениями «многие ко многим», в таблице ассоциаций настраиваются директивы FOREIGN KEY. Эти директивы могут справиться с задачей автоматического удаления из таблицы ассоциаций, но не могут обеспечить автоматическое удаление самих связанных объектов.

В этом случае директива relationship.passive_deletes может избавить нас от дополнительных операторов SELECT во время операции удаления, но все еще остаются некоторые коллекции, которые ORM будет продолжать загружать, чтобы найти затронутые дочерние объекты и правильно их обработать.

В этой конфигурации мы настраиваем ON DELETE CASCADE на оба ограничения внешнего ключа таблицы ассоциации. Мы настраиваем cascade="all, delete" на стороне отношения родитель->ребенок, а затем мы можем настроить passive_deletes=True на другой стороне двунаправленного отношения, как показано ниже:

association_table = Table(
    "association",
    Base.metadata,
    Column("left_id", Integer, ForeignKey("left.id", ondelete="CASCADE")),
    Column("right_id", Integer, ForeignKey("right.id", ondelete="CASCADE")),
)


class Parent(Base):
    __tablename__ = "left"
    id = mapped_column(Integer, primary_key=True)
    children = relationship(
        "Child",
        secondary=association_table,
        back_populates="parents",
        cascade="all, delete",
    )


class Child(Base):
    __tablename__ = "right"
    id = mapped_column(Integer, primary_key=True)
    parents = relationship(
        "Parent",
        secondary=association_table,
        back_populates="children",
        passive_deletes=True,
    )

Используя приведенную выше конфигурацию, удаление объекта Parent происходит следующим образом:

1. Объект Parent помечается для удаления с помощью Session.delete().

2. Когда происходит flush, если коллекция Parent.children не загружена, ORM сначала выпустит оператор SELECT, чтобы загрузить объекты Child, соответствующие Parent.children.

3. Затем он будет выдавать утверждения DELETE для строк в association, которые соответствуют этой родительской строке.

4. для каждого объекта Child, затронутого этим немедленным удалением, поскольку passive_deletes=True настроен, единице работы не нужно будет пытаться выдавать операторы SELECT для каждой коллекции Child.parents, поскольку предполагается, что соответствующие строки в association будут удалены.

5. Затем выдаются утверждения DELETE для каждого объекта Child, который был загружен из Parent.children.