📝 Update release notes

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>

.github/workflows/build-docs.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     # For pull requests it's not necessary to checkout the code but for the main branch it is
-    - uses: dorny/paths-filter@v2
+    - uses: dorny/paths-filter@v3
       id: filter
       with:
         filters: |
@@ -49,7 +49,7 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         id: cache
         with:
           path: ${{ env.pythonLocation }}
@@ -63,7 +63,7 @@ jobs:
           pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
           pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
           pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}
           path: .cache

.github/workflows/publish.yml

@@ -34,4 +34,4 @@ jobs:
           TIANGOLO_BUILD_PACKAGE: ${{ matrix.package }}
         run: python -m build
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@v1.8.11
+        uses: pypa/gh-action-pypi-publish@v1.9.0

.github/workflows/test.yml

@@ -47,7 +47,7 @@ jobs:
         if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }}
         with:
           limit-access-to-actor: true
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         id: cache
         with:
           path: ${{ env.pythonLocation }}

docs/release-notes.md

@@ -2,6 +2,26 @@
 
 ## Latest Changes
 
+## 0.0.21
+
+### Features
+
+* ✨ Add support for cascade delete relationships: `cascade_delete`, `ondelete`, and `passive_deletes`. PR [#983](https://github.com/tiangolo/sqlmodel/pull/983) by [@estebanx64](https://github.com/estebanx64).
+  * New docs at: [Cascade Delete Relationships](https://sqlmodel.tiangolo.com/tutorial/relationship-attributes/cascade-delete-relationships/).
+
+### Docs
+
+* 📝 Update docs . PR [#1003](https://github.com/tiangolo/sqlmodel/pull/1003) by [@alejsdev](https://github.com/alejsdev).
+
+### Internal
+
+* ⬆ Bump actions/cache from 3 to 4. PR [#783](https://github.com/tiangolo/sqlmodel/pull/783) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump cairosvg from 2.7.0 to 2.7.1. PR [#919](https://github.com/tiangolo/sqlmodel/pull/919) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump jinja2 from 3.1.3 to 3.1.4. PR [#974](https://github.com/tiangolo/sqlmodel/pull/974) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump pypa/gh-action-pypi-publish from 1.8.11 to 1.9.0. PR [#987](https://github.com/tiangolo/sqlmodel/pull/987) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump mkdocstrings[python] from 0.23.0 to 0.25.1. PR [#927](https://github.com/tiangolo/sqlmodel/pull/927) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump dorny/paths-filter from 2 to 3. PR [#972](https://github.com/tiangolo/sqlmodel/pull/972) by [@dependabot[bot]](https://github.com/apps/dependabot).
+
 ## 0.0.20
 
 ### Features

docs/tutorial/automatic-id-none-refresh.md

@@ -4,7 +4,7 @@ In the previous chapter, we saw how to add rows to the database using **SQLModel
 
 Now let's talk a bit about why the `id` field **can't be `NULL`** on the database because it's a **primary key**, and we declare it using `Field(primary_key=True)`.
 
-But the same `id` field actually **can be `None`** in the Python code, so we declare the type with `Optional[int]`, and set the default value to `Field(default=None)`:
+But the same `id` field actually **can be `None`** in the Python code, so we declare the type with `int | None (or Optional[int])`, and set the default value to `Field(default=None)`:
 
 //// tab | Python 3.10+
 

docs/tutorial/create-db-and-table.md

@@ -145,7 +145,7 @@ Let's now see with more detail these field/column declarations.
 
 ### Optional Fields, Nullable Columns
 
-Let's start with `age`, notice that it has a type of `Optional[int]`.
+Let's start with `age`, notice that it has a type of `int | None (or Optional[int])`.
 
 And we import that `Optional` from the `typing` standard module.
 

docs/tutorial/relationship-attributes/create-and-update-relationships.md

@@ -134,7 +134,7 @@ Now let's do all that, but this time using the new, shiny `Relationship` attribu
 
 Now we can create the `Team` instances and pass them directly to the new `team` argument when creating the `Hero` instances, as `team=team_preventers` instead of `team_id=team_preventers.id`.
 
-And thanks to SQLAlchemy and how it works underneath, these teams don't even have to have an ID yet, but because we are assigning the whole object to each hero, those teams **will be automatically created** in the database, the automatic ID will be generated, and will be set in the `team_id` column for each of the corresponding hero rows.
+And thanks to SQLAlchemy and how it works underneath, these teams don't even need to have an ID yet, but because we are assigning the whole object to each hero, those teams **will be automatically created** in the database, the automatic ID will be generated, and will be set in the `team_id` column for each of the corresponding hero rows.
 
 In fact, now we don't even have to put the teams explicitly in the session with `session.add(team)`, because these `Team` instances are **already associated** with heroes that **we do** `add` to the session.
 

docs/tutorial/where.md

@@ -1250,7 +1250,7 @@ It would be an error telling you that
 
 > `Hero.age` is potentially `None`, and you cannot compare `None` with `>`
 
-This is because as we are using pure and plain Python annotations for the fields, `age` is indeed annotated as `Optional[int]`, which means `int` or `None`.
+This is because as we are using pure and plain Python annotations for the fields, `age` is indeed annotated as `int | None (or Optional[int])`.
 
 By using this simple and standard Python type annotations we get the benefit of the extra simplicity and the inline error checks when creating or using instances. ✨
 

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial001.py

@@ -0,0 +1,110 @@
+from typing import List, Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: List["Hero"] = Relationship(back_populates="team", cascade_delete=True)
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="CASCADE"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion not found:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E not found:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial001_py310.py

@@ -0,0 +1,106 @@
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", cascade_delete=True)
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+    team_id: int | None = Field(default=None, foreign_key="team.id", ondelete="CASCADE")
+    team: Team | None = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion not found:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E not found:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial001_py39.py

@@ -0,0 +1,110 @@
+from typing import Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", cascade_delete=True)
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="CASCADE"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion not found:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E not found:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial002.py

@@ -0,0 +1,110 @@
+from typing import List, Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: List["Hero"] = Relationship(back_populates="team")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial002_py310.py

@@ -0,0 +1,108 @@
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team")
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+    team_id: int | None = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Team | None = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial002_py39.py

@@ -0,0 +1,110 @@
+from typing import Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial003.py

@@ -0,0 +1,112 @@
+from typing import List, Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: List["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial003_py310.py

@@ -0,0 +1,110 @@
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+    team_id: int | None = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Team | None = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial003_py39.py

@@ -0,0 +1,112 @@
+from typing import Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="SET NULL"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial004.py

@@ -0,0 +1,111 @@
+from typing import List, Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: List["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial004_py310.py

@@ -0,0 +1,109 @@
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+    team_id: int | None = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Team | None = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial004_py39.py

@@ -0,0 +1,111 @@
+from typing import Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    delete_team()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial005.py

@@ -0,0 +1,124 @@
+from typing import List, Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: List["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def remove_team_heroes():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        team.heroes.clear()
+        session.add(team)
+        session.commit()
+        session.refresh(team)
+        print("Team with removed heroes:", team)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    remove_team_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial005_py310.py

@@ -0,0 +1,122 @@
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+    team_id: int | None = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Team | None = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def remove_team_heroes():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        team.heroes.clear()
+        session.add(team)
+        session.commit()
+        session.refresh(team)
+        print("Team with removed heroes:", team)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    remove_team_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial005_py39.py

@@ -0,0 +1,124 @@
+from typing import Optional
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select, text
+
+
+class Team(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    headquarters: str
+
+    heroes: list["Hero"] = Relationship(back_populates="team", passive_deletes="all")
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+    team_id: Optional[int] = Field(
+        default=None, foreign_key="team.id", ondelete="RESTRICT"
+    )
+    team: Optional[Team] = Relationship(back_populates="heroes")
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+    with engine.connect() as connection:
+        connection.execute(text("PRAGMA foreign_keys=ON"))  # for SQLite only
+
+
+def create_heroes():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+        session.refresh(hero_spider_boy)
+        print("Updated hero:", hero_spider_boy)
+
+        hero_black_lion = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+        hero_sure_e = Hero(name="Princess Sure-E", secret_name="Sure-E")
+        team_wakaland = Team(
+            name="Wakaland",
+            headquarters="Wakaland Capital City",
+            heroes=[hero_black_lion, hero_sure_e],
+        )
+        session.add(team_wakaland)
+        session.commit()
+        session.refresh(team_wakaland)
+        print("Team Wakaland:", team_wakaland)
+
+
+def remove_team_heroes():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        team.heroes.clear()
+        session.add(team)
+        session.commit()
+        session.refresh(team)
+        print("Team with removed heroes:", team)
+
+
+def delete_team():
+    with Session(engine) as session:
+        statement = select(Team).where(Team.name == "Wakaland")
+        team = session.exec(statement).one()
+        session.delete(team)
+        session.commit()
+        print("Deleted team:", team)
+
+
+def select_deleted_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(Hero.name == "Black Lion")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Black Lion has no team:", hero)
+
+        statement = select(Hero).where(Hero.name == "Princess Sure-E")
+        result = session.exec(statement)
+        hero = result.first()
+        print("Princess Sure-E has no team:", hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    remove_team_heroes()
+    delete_team()
+    select_deleted_heroes()
+
+
+if __name__ == "__main__":
+    main()

mkdocs.yml

@@ -74,6 +74,7 @@ nav:
       - tutorial/relationship-attributes/read-relationships.md
       - tutorial/relationship-attributes/remove-relationships.md
       - tutorial/relationship-attributes/back-populates.md
+      - tutorial/relationship-attributes/cascade-delete-relationships.md
       - tutorial/relationship-attributes/type-annotation-strings.md
     - Many to Many:
       - tutorial/many-to-many/index.md

requirements-docs.txt

@@ -10,8 +10,8 @@ jieba==0.42.1
 # For image processing by Material for MkDocs
 pillow==10.1.0
 # For image processing by Material for MkDocs
-cairosvg==2.7.0
-mkdocstrings[python]==0.23.0
+cairosvg==2.7.1
+mkdocstrings[python]==0.25.1
 # Enable griffe-typingdoc once dropping Python 3.7 and upgrading typing-extensions
 # griffe-typingdoc==0.2.5
 # For griffe, it formats with black

requirements-tests.txt

@@ -9,7 +9,7 @@ fastapi >=0.103.2
 httpx ==0.24.1
 # TODO: upgrade when deprecating Python 3.7
 dirty-equals ==0.6.0
-jinja2 ==3.1.3
+jinja2 ==3.1.4
 # Pin typing-extensions until Python 3.8 is deprecated or the issue with dirty-equals
 # is fixed, maybe fixed after dropping Python 3.7 and upgrading dirty-equals
 typing-extensions ==4.6.1

sqlmodel/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.20"
+__version__ = "0.0.21"
 
 # Re-export from SQLAlchemy
 from sqlalchemy.engine import create_engine as create_engine

sqlmodel/main.py

@@ -91,6 +91,7 @@ if TYPE_CHECKING:
 _T = TypeVar("_T")
 NoArgAnyCallable = Callable[[], Any]
 IncEx = Union[Set[int], Set[str], Dict[int, Any], Dict[str, Any], None]
+OnDeleteType = Literal["CASCADE", "SET NULL", "RESTRICT"]
 
 
 def __dataclass_transform__(
@@ -108,6 +109,7 @@ class FieldInfo(PydanticFieldInfo):
         primary_key = kwargs.pop("primary_key", False)
         nullable = kwargs.pop("nullable", Undefined)
         foreign_key = kwargs.pop("foreign_key", Undefined)
+        ondelete = kwargs.pop("ondelete", Undefined)
         unique = kwargs.pop("unique", False)
         index = kwargs.pop("index", Undefined)
         sa_type = kwargs.pop("sa_type", Undefined)
@@ -132,13 +134,17 @@ class FieldInfo(PydanticFieldInfo):
                 )
             if nullable is not Undefined:
                 raise RuntimeError(
-                    "Passing nullable is not supported when " "also passing a sa_column"
+                    "Passing nullable is not supported when also passing a sa_column"
                 )
             if foreign_key is not Undefined:
                 raise RuntimeError(
                     "Passing foreign_key is not supported when "
                     "also passing a sa_column"
                 )
+            if ondelete is not Undefined:
+                raise RuntimeError(
+                    "Passing ondelete is not supported when also passing a sa_column"
+                )
             if unique is not Undefined:
                 raise RuntimeError(
                     "Passing unique is not supported when also passing a sa_column"
@@ -151,10 +157,14 @@ class FieldInfo(PydanticFieldInfo):
                 raise RuntimeError(
                     "Passing sa_type is not supported when also passing a sa_column"
                 )
+        if ondelete is not Undefined:
+            if foreign_key is Undefined:
+                raise RuntimeError("ondelete can only be used with foreign_key")
         super().__init__(default=default, **kwargs)
         self.primary_key = primary_key
         self.nullable = nullable
         self.foreign_key = foreign_key
+        self.ondelete = ondelete
         self.unique = unique
         self.index = index
         self.sa_type = sa_type
@@ -168,6 +178,8 @@ class RelationshipInfo(Representation):
         self,
         *,
         back_populates: Optional[str] = None,
+        cascade_delete: Optional[bool] = False,
+        passive_deletes: Optional[Union[bool, Literal["all"]]] = False,
         link_model: Optional[Any] = None,
         sa_relationship: Optional[RelationshipProperty] = None,  # type: ignore
         sa_relationship_args: Optional[Sequence[Any]] = None,
@@ -185,12 +197,15 @@ class RelationshipInfo(Representation):
                     "also passing a sa_relationship"
                 )
         self.back_populates = back_populates
+        self.cascade_delete = cascade_delete
+        self.passive_deletes = passive_deletes
         self.link_model = link_model
         self.sa_relationship = sa_relationship
         self.sa_relationship_args = sa_relationship_args
         self.sa_relationship_kwargs = sa_relationship_kwargs
 
 
+# include sa_type, sa_column_args, sa_column_kwargs
 @overload
 def Field(
     default: Any = Undefined,
@@ -234,6 +249,62 @@ def Field(
 ) -> Any: ...
 
 
+# When foreign_key is str, include ondelete
+# include sa_type, sa_column_args, sa_column_kwargs
+@overload
+def Field(
+    default: Any = Undefined,
+    *,
+    default_factory: Optional[NoArgAnyCallable] = None,
+    alias: Optional[str] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    exclude: Union[
+        AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any
+    ] = None,
+    include: Union[
+        AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any
+    ] = None,
+    const: Optional[bool] = None,
+    gt: Optional[float] = None,
+    ge: Optional[float] = None,
+    lt: Optional[float] = None,
+    le: Optional[float] = None,
+    multiple_of: Optional[float] = None,
+    max_digits: Optional[int] = None,
+    decimal_places: Optional[int] = None,
+    min_items: Optional[int] = None,
+    max_items: Optional[int] = None,
+    unique_items: Optional[bool] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    allow_mutation: bool = True,
+    regex: Optional[str] = None,
+    discriminator: Optional[str] = None,
+    repr: bool = True,
+    primary_key: Union[bool, UndefinedType] = Undefined,
+    foreign_key: str,
+    ondelete: Union[OnDeleteType, UndefinedType] = Undefined,
+    unique: Union[bool, UndefinedType] = Undefined,
+    nullable: Union[bool, UndefinedType] = Undefined,
+    index: Union[bool, UndefinedType] = Undefined,
+    sa_type: Union[Type[Any], UndefinedType] = Undefined,
+    sa_column_args: Union[Sequence[Any], UndefinedType] = Undefined,
+    sa_column_kwargs: Union[Mapping[str, Any], UndefinedType] = Undefined,
+    schema_extra: Optional[Dict[str, Any]] = None,
+) -> Any: ...
+
+
+# Include sa_column, don't include
+# primary_key
+# foreign_key
+# ondelete
+# unique
+# nullable
+# index
+# sa_type
+# sa_column_args
+# sa_column_kwargs
 @overload
 def Field(
     default: Any = Undefined,
@@ -302,6 +373,7 @@ def Field(
     repr: bool = True,
     primary_key: Union[bool, UndefinedType] = Undefined,
     foreign_key: Any = Undefined,
+    ondelete: Union[OnDeleteType, UndefinedType] = Undefined,
     unique: Union[bool, UndefinedType] = Undefined,
     nullable: Union[bool, UndefinedType] = Undefined,
     index: Union[bool, UndefinedType] = Undefined,
@@ -339,6 +411,7 @@ def Field(
         repr=repr,
         primary_key=primary_key,
         foreign_key=foreign_key,
+        ondelete=ondelete,
         unique=unique,
         nullable=nullable,
         index=index,
@@ -356,6 +429,8 @@ def Field(
 def Relationship(
     *,
     back_populates: Optional[str] = None,
+    cascade_delete: Optional[bool] = False,
+    passive_deletes: Optional[Union[bool, Literal["all"]]] = False,
     link_model: Optional[Any] = None,
     sa_relationship_args: Optional[Sequence[Any]] = None,
     sa_relationship_kwargs: Optional[Mapping[str, Any]] = None,
@@ -366,6 +441,8 @@ def Relationship(
 def Relationship(
     *,
     back_populates: Optional[str] = None,
+    cascade_delete: Optional[bool] = False,
+    passive_deletes: Optional[Union[bool, Literal["all"]]] = False,
     link_model: Optional[Any] = None,
     sa_relationship: Optional[RelationshipProperty[Any]] = None,
 ) -> Any: ...
@@ -374,6 +451,8 @@ def Relationship(
 def Relationship(
     *,
     back_populates: Optional[str] = None,
+    cascade_delete: Optional[bool] = False,
+    passive_deletes: Optional[Union[bool, Literal["all"]]] = False,
     link_model: Optional[Any] = None,
     sa_relationship: Optional[RelationshipProperty[Any]] = None,
     sa_relationship_args: Optional[Sequence[Any]] = None,
@@ -381,6 +460,8 @@ def Relationship(
 ) -> Any:
     relationship_info = RelationshipInfo(
         back_populates=back_populates,
+        cascade_delete=cascade_delete,
+        passive_deletes=passive_deletes,
         link_model=link_model,
         sa_relationship=sa_relationship,
         sa_relationship_args=sa_relationship_args,
@@ -531,6 +612,10 @@ class SQLModelMetaclass(ModelMetaclass, DeclarativeMeta):
                 rel_kwargs: Dict[str, Any] = {}
                 if rel_info.back_populates:
                     rel_kwargs["back_populates"] = rel_info.back_populates
+                if rel_info.cascade_delete:
+                    rel_kwargs["cascade"] = "all, delete-orphan"
+                if rel_info.passive_deletes:
+                    rel_kwargs["passive_deletes"] = rel_info.passive_deletes
                 if rel_info.link_model:
                     ins = inspect(rel_info.link_model)
                     local_table = getattr(ins, "local_table")  # noqa: B009
@@ -642,8 +727,14 @@ def get_column_from_field(field: Any) -> Column:  # type: ignore
     if unique is Undefined:
         unique = False
     if foreign_key:
+        if field_info.ondelete == "SET NULL" and not nullable:
+            raise RuntimeError('ondelete="SET NULL" requires nullable=True')
         assert isinstance(foreign_key, str)
-        args.append(ForeignKey(foreign_key))
+        ondelete = getattr(field_info, "ondelete", Undefined)
+        if ondelete is Undefined:
+            ondelete = None
+        assert isinstance(ondelete, (str, type(None)))  # for typing
+        args.append(ForeignKey(foreign_key, ondelete=ondelete))
     kwargs = {
         "primary_key": primary_key,
         "nullable": nullable,

tests/test_field_sa_column.py

@@ -108,3 +108,14 @@ def test_sa_column_no_index() -> None:
                 index=True,
                 sa_column=Column(Integer, primary_key=True),
             )
+
+
+def test_sa_column_no_ondelete() -> None:
+    with pytest.raises(RuntimeError):
+
+        class Item(SQLModel, table=True):
+            id: Optional[int] = Field(
+                default=None,
+                sa_column=Column(Integer, primary_key=True),
+                ondelete="CASCADE",
+            )

tests/test_ondelete_raises.py

@@ -0,0 +1,37 @@
+from typing import Any, List, Union
+
+import pytest
+from sqlmodel import Field, Relationship, SQLModel
+
+
+def test_ondelete_requires_nullable(clear_sqlmodel: Any) -> None:
+    with pytest.raises(RuntimeError) as exc:
+
+        class Team(SQLModel, table=True):
+            id: Union[int, None] = Field(default=None, primary_key=True)
+
+            heroes: List["Hero"] = Relationship(
+                back_populates="team", passive_deletes="all"
+            )
+
+        class Hero(SQLModel, table=True):
+            id: Union[int, None] = Field(default=None, primary_key=True)
+            name: str = Field(index=True)
+            secret_name: str
+            age: Union[int, None] = Field(default=None, index=True)
+
+            team_id: int = Field(foreign_key="team.id", ondelete="SET NULL")
+            team: Team = Relationship(back_populates="heroes")
+
+    assert 'ondelete="SET NULL" requires nullable=True' in str(exc.value)
+
+
+def test_ondelete_requires_foreign_key(clear_sqlmodel: Any) -> None:
+    with pytest.raises(RuntimeError) as exc:
+
+        class Team(SQLModel, table=True):
+            id: Union[int, None] = Field(default=None, primary_key=True)
+
+            age: int = Field(ondelete="CASCADE")
+
+    assert "ondelete can only be used with foreign_key" in str(exc.value)

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial001.py

@@ -0,0 +1,72 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial001 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        [
+            "Deleted team:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        ["Black Lion not found:", None],
+        ["Princess Sure-E not found:", None],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial001_py310.py

@@ -0,0 +1,73 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial001_py310 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        [
+            "Deleted team:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        ["Black Lion not found:", None],
+        ["Princess Sure-E not found:", None],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial001_py39.py

@@ -0,0 +1,73 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py39
+
+
+@needs_py39
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial001_py39 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        [
+            "Deleted team:",
+            {"name": "Wakaland", "id": 3, "headquarters": "Wakaland Capital City"},
+        ],
+        ["Black Lion not found:", None],
+        ["Princess Sure-E not found:", None],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial002.py

@@ -0,0 +1,90 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial002 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial002_py310.py

@@ -0,0 +1,91 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial002_py310 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial002_py39.py

@@ -0,0 +1,91 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py39
+
+
+@needs_py39
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial002_py39 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial003.py

@@ -0,0 +1,90 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from tests.conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial003 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial003_py310.py

@@ -0,0 +1,91 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial003_py310 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial003_py39.py

@@ -0,0 +1,91 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py39
+
+
+@needs_py39
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial003_py39 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial004.py

@@ -0,0 +1,106 @@
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from sqlmodel import Session, create_engine, select
+
+from tests.conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial004 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.create_db_and_tables()
+        mod.create_heroes()
+        mod.select_deleted_heroes()
+        with Session(mod.engine) as session:
+            team = session.exec(
+                select(mod.Team).where(mod.Team.name == "Wakaland")
+            ).one()
+            team.heroes.clear()
+            session.add(team)
+            session.commit()
+        mod.delete_team()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+    ]
+
+    with pytest.raises(IntegrityError) as exc:
+        mod.main()
+    assert "FOREIGN KEY constraint failed" in str(exc.value)

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial004_py310.py

@@ -0,0 +1,107 @@
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from sqlmodel import Session, create_engine, select
+
+from tests.conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial004_py310 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.create_db_and_tables()
+        mod.create_heroes()
+        mod.select_deleted_heroes()
+        with Session(mod.engine) as session:
+            team = session.exec(
+                select(mod.Team).where(mod.Team.name == "Wakaland")
+            ).one()
+            team.heroes.clear()
+            session.add(team)
+            session.commit()
+        mod.delete_team()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+    ]
+
+    with pytest.raises(IntegrityError) as exc:
+        mod.main()
+    assert "FOREIGN KEY constraint failed" in str(exc.value)

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial004_py39.py

@@ -0,0 +1,107 @@
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from sqlmodel import Session, create_engine, select
+
+from tests.conftest import get_testing_print_function, needs_py39
+
+
+@needs_py39
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial004_py39 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.create_db_and_tables()
+        mod.create_heroes()
+        mod.select_deleted_heroes()
+        with Session(mod.engine) as session:
+            team = session.exec(
+                select(mod.Team).where(mod.Team.name == "Wakaland")
+            ).one()
+            team.heroes.clear()
+            session.add(team)
+            session.commit()
+        mod.delete_team()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 1,
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": 48,
+                "id": 2,
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "age": None,
+                "id": 3,
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "age": 35,
+                "id": 4,
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "age": None,
+                "id": 5,
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": 3,
+            },
+        ],
+        [
+            "Deleted team:",
+            {"headquarters": "Wakaland Capital City", "id": 3, "name": "Wakaland"},
+        ],
+    ]
+
+    with pytest.raises(IntegrityError) as exc:
+        mod.main()
+    assert "FOREIGN KEY constraint failed" in str(exc.value)

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial005.py

@@ -0,0 +1,94 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from tests.conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial005 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Team with removed heroes:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+                "id": 4,
+                "age": 35,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+                "id": 5,
+                "age": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial005_py310.py

@@ -0,0 +1,95 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from tests.conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial005_py310 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Team with removed heroes:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+                "id": 4,
+                "age": 35,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+                "id": 5,
+                "age": None,
+            },
+        ],
+    ]

tests/test_tutorial/test_relationship_attributes/test_delete_records_relationship/test_tutorial005_py39.py

@@ -0,0 +1,95 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from tests.conftest import get_testing_print_function, needs_py39
+
+
+@needs_py39
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.cascade_delete_relationships import (
+        tutorial005_py39 as mod,
+    )
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            "Created hero:",
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "team_id": 1,
+                "id": 1,
+                "age": None,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Rusty-Man",
+                "secret_name": "Tommy Sharp",
+                "team_id": 2,
+                "id": 2,
+                "age": 48,
+            },
+        ],
+        [
+            "Created hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": None,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Updated hero:",
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "team_id": 2,
+                "id": 3,
+                "age": None,
+            },
+        ],
+        [
+            "Team Wakaland:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Team with removed heroes:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Deleted team:",
+            {"id": 3, "headquarters": "Wakaland Capital City", "name": "Wakaland"},
+        ],
+        [
+            "Black Lion has no team:",
+            {
+                "name": "Black Lion",
+                "secret_name": "Trevor Challa",
+                "team_id": None,
+                "id": 4,
+                "age": 35,
+            },
+        ],
+        [
+            "Princess Sure-E has no team:",
+            {
+                "name": "Princess Sure-E",
+                "secret_name": "Sure-E",
+                "team_id": None,
+                "id": 5,
+                "age": None,
+            },
+        ],
+    ]