📝 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 }}

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ default_language_version:
     python: python3.10
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
     -   id: check-added-large-files
     -   id: check-toml
@@ -14,7 +14,7 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.7
+    rev: v0.5.2
     hooks:
     -   id: ruff
         args:

docs/advanced/uuid.md

@@ -0,0 +1,342 @@
+# UUID (Universally Unique Identifiers)
+
+We have discussed some data types like `str`, `int`, etc.
+
+There's another data type called `UUID` (Universally Unique Identifier).
+
+You might have seen **UUIDs**, for example in URLs. They look something like this:
+
+```
+4ff2dab7-bffe-414d-88a5-1826b9fea8df
+```
+
+UUIDs can be particularly useful as an alternative to auto-incrementing integers for **primary keys**.
+
+/// info
+
+Official support for UUIDs was added in SQLModel version `0.0.20`.
+
+///
+
+## About UUIDs
+
+UUIDs are numbers with 128 bits, that is, 16 bytes.
+
+They are normally seen as 32 <abbr title="numbers in base 16 (instead of base 10), using letters from A to F to represent the numbers from 10 to 15">hexadecimal</abbr> characters separated by dashes.
+
+There are several versions of UUID, some versions include the current time in the bytes, but **UUIDs version 4** are mainly random, the way they are generated makes them virtually **unique**.
+
+### Distributed UUIDs
+
+You could generate one UUID in one computer, and someone else could generate another UUID in another computer, and it would be almost **impossible** for both UUIDs to be the **same**.
+
+This means that you don't have to wait for the DB to generate the ID for you, you can **generate it in code before sending it to the database**, because you can be quite certain it will be unique.
+
+/// note | Technical Details
+
+Because the number of possible UUIDs is so large (2^128), the probability of generating the same UUID version 4 (the random ones) twice is very low.
+
+If you had 103 trillion version 4 UUIDs stored in the database, the probability of generating a duplicated new one is one in a billion. 🤓
+
+///
+
+For the same reason, if you decided to migrate your database, combine it with another database and mix records, etc. you would most probably be able to **just use the same UUIDs** you had originally.
+
+/// warning
+
+There's still a chance you could have a collision, but it's very low. In most cases you could assume you wouldn't have it, but it would be good to be prepared for it.
+
+///
+
+### UUIDs Prevent Information Leakage
+
+Because UUIDs version 4 are **random**, you could give these IDs to the application users or to other systems, **without exposing information** about your application.
+
+When using **auto-incremented integers** for primary keys, you could implicitly expose information about your system. For example, someone could create a new hero, and by getting the hero ID `20` **they would know that you have 20 heroes** in your system (or even less, if some heroes were already deleted).
+
+### UUID Storage
+
+Because UUIDs are 16 bytes, they would **consume more space** in the database than a smaller auto-incremented integer (commonly 4 bytes).
+
+Depending on the database you use, UUIDs could have **better or worse performance**. If you are concerned about that, you should check the documentation for the specific database.
+
+SQLite doesn't have a specific UUID type, so it will store the UUID as a string. Other databases like Postgres have a specific UUID type which would result in better performance and space usage than strings.
+
+## Models with UUIDs
+
+To use UUIDs as primary keys we need to import `uuid`, which is part of the Python standard library (we don't have to install anything) and use `uuid.UUID` as the **type** for the ID field.
+
+We also want the Python code to **generate a new UUID** when creating a new instance, so we use `default_factory`.
+
+The parameter `default_factory` takes a function (or in general, a "<abbr title="Something that can be called as a function.">callable</abbr>"). This function will be **called when creating a new instance** of the model and the value returned by the function will be used as the default value for the field.
+
+For the function in `default_factory` we pass `uuid.uuid4`, which is a function that generates a **new UUID version 4**.
+
+/// tip
+
+We don't call `uuid.uuid4()` ourselves in the code (we don't put the parenthesis). Instead, we pass the function itself, just `uuid.uuid4`, so that SQLModel can call it every time we create a new instance.
+
+///
+
+This means that the UUID will be generated in the Python code, **before sending the data to the database**.
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1  7"
+{!./docs_src/advanced/uuid/tutorial001_py310.py[ln:1-10]!}
+
+# Code below omitted 👇
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python hl_lines="1  8"
+{!./docs_src/advanced/uuid/tutorial001.py[ln:1-11]!}
+
+# Code below omitted 👇
+```
+
+////
+
+/// details | 👀 Full file preview
+
+//// tab | Python 3.10+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001_py310.py!}
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001.py!}
+```
+
+////
+
+///
+
+Pydantic has support for <a href="https://docs.pydantic.dev/latest/api/standard_library_types/#uuid" class="external-link" target="_blank">`UUID` types</a>.
+
+For the database, **SQLModel** internally uses <a href="https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Uuid" class="external-link" target="_blank">SQLAlchemy's `Uuid` type</a>.
+
+### Create a Record with a UUID
+
+When creating a `Hero` record, the `id` field will be **automatically populated** with a new UUID because we set `default_factory=uuid.uuid4`.
+
+As `uuid.uuid4` will be called when creating the model instance, even before sending it to the database, we can **access and use the ID right away**.
+
+And that **same ID (a UUID)** will be saved in the database.
+
+//// tab | Python 3.10+
+
+```Python hl_lines="5  7  9  14"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial001_py310.py[ln:23-34]!}
+
+# Code below omitted 👇
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python hl_lines="5  7  9  14"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial001.py[ln:24-35]!}
+
+# Code below omitted 👇
+```
+
+////
+
+/// details | 👀 Full file preview
+
+//// tab | Python 3.10+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001_py310.py!}
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001.py!}
+```
+
+////
+
+///
+
+### Select a Hero
+
+We can do the same operations we could do with other fields.
+
+For example we can **select a hero by ID**:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="15"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial001_py310.py[ln:37-54]!}
+
+# Code below omitted 👇
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python hl_lines="15"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial001.py[ln:38-55]!}
+
+# Code below omitted 👇
+```
+
+////
+
+/// details | 👀 Full file preview
+
+//// tab | Python 3.10+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001_py310.py!}
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial001.py!}
+```
+
+////
+
+///
+
+/// tip
+
+Even if a database like SQLite stores the UUID as a string, we can select and run comparisons using a Python UUID object and it will work.
+
+SQLModel (actually SQLAlchemy) will take care of making it work. ✨
+
+///
+
+#### Select with `session.get()`
+
+We could also select by ID with `session.get()`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="15"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial002_py310.py[ln:37-54]!}
+
+# Code below omitted 👇
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python hl_lines="15"
+# Code above omitted 👆
+
+{!./docs_src/advanced/uuid/tutorial002.py[ln:38-55]!}
+
+# Code below omitted 👇
+```
+
+////
+
+/// details | 👀 Full file preview
+
+//// tab | Python 3.10+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial002_py310.py!}
+```
+
+////
+
+//// tab | Python 3.7+
+
+```Python
+{!./docs_src/advanced/uuid/tutorial002.py!}
+```
+
+////
+
+///
+
+The same way as with other fields, we could update, delete, etc. 🚀
+
+### Run the program
+
+If you run the program, you will see the **UUID** generated in the Python code, and then the record **saved in the database with the same UUID**.
+
+<div class="termy">
+
+```console
+$ python app.py
+
+// Some boilerplate and previous output omitted 😉
+
+// In SQLite, the UUID will be stored as a string
+// other DBs like Postgres have a specific UUID type
+CREATE TABLE hero (
+        id CHAR(32) NOT NULL,
+        name VARCHAR NOT NULL,
+        secret_name VARCHAR NOT NULL,
+        age INTEGER,
+        PRIMARY KEY (id)
+)
+
+// Before saving in the DB we already have the UUID
+The hero before saving in the DB
+name='Deadpond' secret_name='Dive Wilson' id=UUID('0e44c1a6-88d3-4a35-8b8a-307faa2def28') age=None
+The hero ID was already set
+0e44c1a6-88d3-4a35-8b8a-307faa2def28
+
+// The SQL statement to insert the record uses our UUID
+INSERT INTO hero (id, name, secret_name, age) VALUES (?, ?, ?, ?)
+('0e44c1a688d34a358b8a307faa2def28', 'Deadpond', 'Dive Wilson', None)
+
+// And indeed, the record was saved with the UUID we created 😎
+After saving in the DB
+age=None id=UUID('0e44c1a6-88d3-4a35-8b8a-307faa2def28') name='Deadpond' secret_name='Dive Wilson'
+
+// Now we create a new hero (to select it in a bit)
+Created hero:
+age=None id=UUID('9d90d186-85db-4eaa-891a-def7b4ae2dab') name='Spider-Boy' secret_name='Pedro Parqueador'
+Created hero ID:
+9d90d186-85db-4eaa-891a-def7b4ae2dab
+
+// And now we select it
+Selected hero:
+age=None id=UUID('9d90d186-85db-4eaa-891a-def7b4ae2dab') name='Spider-Boy' secret_name='Pedro Parqueador'
+Selected hero ID:
+9d90d186-85db-4eaa-891a-def7b4ae2dab
+```
+
+</div>
+
+## Learn More
+
+You can learn more about **UUIDs** in:
+
+* The official <a href="https://docs.python.org/3/library/uuid.html" class="external-link" target="_blank">Python docs for UUID</a>.
+* The <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier" class="external-link" target="_blank">Wikipedia for UUID</a>.

docs/css/custom.css

@@ -8,6 +8,10 @@
     white-space: pre-wrap;
 }
 
+.termy .linenos {
+    display: none;
+}
+
 a.external-link::after {
     /* \00A0 is a non-breaking space
         to make the mark be on the same line as the link

docs/js/custom.js

@@ -13,7 +13,7 @@ function setupTermynal() {
 
     function createTermynals() {
         document
-            .querySelectorAll(`.${termynalActivateClass} .highlight`)
+            .querySelectorAll(`.${termynalActivateClass} .highlight code`)
             .forEach(node => {
                 const text = node.textContent;
                 const lines = text.split("\n");

docs/release-notes.md

@@ -2,6 +2,47 @@
 
 ## 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
+
+* ✨ Add official UUID support, docs and tests, internally using new SQLAlchemy 2.0 types. Initial PR [#992](https://github.com/tiangolo/sqlmodel/pull/992) by [@estebanx64](https://github.com/estebanx64).
+  * New docs in the [Advanced User Guide: UUID (Universally Unique Identifiers)](https://sqlmodel.tiangolo.com/advanced/uuid/).
+
+### Docs
+
+* ✏️ Fix internal link in `docs/tutorial/create-db-and-table.md`. PR [#911](https://github.com/tiangolo/sqlmodel/pull/911) by [@tfpgh](https://github.com/tfpgh).
+* ✏️ Add missing step in `create-db-and-table-with-db-browser.md`. PR [#976](https://github.com/tiangolo/sqlmodel/pull/976) by [@alejsdev](https://github.com/alejsdev).
+* ✏️ Fix typo in `docs/tutorial`. PR [#943](https://github.com/tiangolo/sqlmodel/pull/943) by [@luco17](https://github.com/luco17).
+* ✏️ Fix typo in `sqlmodel/_compat.py`. PR [#950](https://github.com/tiangolo/sqlmodel/pull/950) by [@Highfire1](https://github.com/Highfire1).
+* ✏️ Update pip installation command in tutorial. PR [#975](https://github.com/tiangolo/sqlmodel/pull/975) by [@alejsdev](https://github.com/alejsdev).
+* ✏️ Fix typo in `docs/tutorial/relationship-attributes/index.md`. PR [#880](https://github.com/tiangolo/sqlmodel/pull/880) by [@UncleGoogle](https://github.com/UncleGoogle).
+
+### Internal
+
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#979](https://github.com/tiangolo/sqlmodel/pull/979) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* 🔨 Update docs Termynal scripts to not include line nums for local dev. PR [#1018](https://github.com/tiangolo/sqlmodel/pull/1018) by [@tiangolo](https://github.com/tiangolo).
+
 ## 0.0.19
 
 ### Fixes

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-with-db-browser.md

@@ -125,6 +125,8 @@ And delete that `./database.db` file in your project directory.
 
 And click again on <kbd>New Database</kbd>.
 
+Save the file with the name `database.db` again.
+
 This time, if you see the dialog to create a new table, just close it by clicking the <kbd>Cancel</kbd> button.
 
 And now, go to the tab <kbd>Execute SQL</kbd>.

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.
 
@@ -354,7 +354,7 @@ But we will talk about it later.
 
 ### Engine Database URL
 
-Each supported database has it's own URL type. For example, for **SQLite** it is `sqlite:///` followed by the file path. For example:
+Each supported database has its own URL type. For example, for **SQLite** it is `sqlite:///` followed by the file path. For example:
 
 * `sqlite:///database.db`
 * `sqlite:///databases/local/application.db`
@@ -470,7 +470,7 @@ If you didn't know about SQLAlchemy before and are just learning **SQLModel**, y
 
 You can read a lot more about the engine in the <a href="https://docs.sqlalchemy.org/en/14/tutorial/engine.html" class="external-link" target="_blank">SQLAlchemy documentation</a>.
 
-**SQLModel** defines it's own `create_engine()` function. It is the same as SQLAlchemy's `create_engine()`, but with the difference that it defaults to use `future=True` (which means that it uses the style of the latest SQLAlchemy, 1.4, and the future 2.0).
+**SQLModel** defines its own `create_engine()` function. It is the same as SQLAlchemy's `create_engine()`, but with the difference that it defaults to use `future=True` (which means that it uses the style of the latest SQLAlchemy, 1.4, and the future 2.0).
 
 And SQLModel's version of `create_engine()` is type annotated internally, so your editor will be able to help you with autocompletion and inline errors.
 
@@ -688,7 +688,7 @@ In the example in the previous chapter we created the table using `TEXT` for som
 
 But in this output SQLAlchemy is using `VARCHAR` instead. Let's see what's going on.
 
-Remember that [each SQL Database has some different variations in what they support?](../databases/#sql-the-language){.internal-link target=_blank}
+Remember that [each SQL Database has some different variations in what they support?](../databases.md#sql-the-language){.internal-link target=_blank}
 
 This is one of the differences. Each database supports some particular **data types**, like `INTEGER` and `TEXT`.
 

docs/tutorial/index.md

@@ -192,7 +192,7 @@ Now, after making sure we are inside of a virtual environment in some way, we ca
 <div class="termy">
 
 ```console
-# (env) $$ python -m pip install sqlmodel
+# (env) $$ pip install sqlmodel
 ---> 100%
 Successfully installed sqlmodel pydantic sqlalchemy
 ```

docs/tutorial/indexes.md

@@ -90,7 +90,7 @@ Do you like **fancy words**? Cool! Programmers tend to like fancy words. 😅
 
 That <abbr title="a recipe, a sequence of predefined steps that achieve a result">algorithm</abbr> I showed you above is called **Binary Search**.
 
-It's called like that because you **search** something by splitting the dictionary (or any ordered list of things) in **two** ("binary" means "two") parts. And you do that process multiple times until you find what you want.
+It's called that because you **search** something by splitting the dictionary (or any ordered list of things) in **two** ("binary" means "two") parts. And you do that process multiple times until you find what you want.
 
 ///
 

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/relationship-attributes/index.md

@@ -4,7 +4,7 @@ In the previous chapters we discussed how to manage databases with tables that h
 
 And then we read the data together with `select()` and using `.where()` or `.join()` to connect it.
 
-Now we will see how to use **Relationship Attributes**, an extra feature of **SQLModel** (and SQLAlchemy) to work with the data in the database in way much more familiar way, and closer to normal Python code.
+Now we will see how to use **Relationship Attributes**, an extra feature of **SQLModel** (and SQLAlchemy), to work with the data in the database in a much more familiar way, and closer to normal Python code.
 
 /// info
 

docs/tutorial/select.md

@@ -713,7 +713,7 @@ In this chapter we are touching some of them.
 
 When importing from `sqlmodel` the `select()` function, you are using **SQLModel**'s version of `select`.
 
-SQLAchemy also has it's own `select`, and SQLModel's `select` uses SQLAlchemy's `select` internally.
+SQLAchemy also has its own `select`, and SQLModel's `select` uses SQLAlchemy's `select` internally.
 
 But SQLModel's version does a lot of **tricks** with type annotations to make sure you get the best **editor support** possible, no matter if you use **VS Code**, **PyCharm**, or something else. ✨
 

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/advanced/uuid/tutorial001.py

@@ -0,0 +1,65 @@
+import uuid
+from typing import Union
+
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+
+class Hero(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Union[int, None] = Field(default=None, index=True)
+
+
+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_hero():
+    with Session(engine) as session:
+        hero = Hero(name="Deadpond", secret_name="Dive Wilson")
+        print("The hero before saving in the DB")
+        print(hero)
+        print("The hero ID was already set")
+        print(hero.id)
+        session.add(hero)
+        session.commit()
+        session.refresh(hero)
+        print("After saving in the DB")
+        print(hero)
+
+
+def select_hero():
+    with Session(engine) as session:
+        hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_2)
+        session.commit()
+        session.refresh(hero_2)
+        hero_id = hero_2.id
+        print("Created hero:")
+        print(hero_2)
+        print("Created hero ID:")
+        print(hero_id)
+
+        statement = select(Hero).where(Hero.id == hero_id)
+        selected_hero = session.exec(statement).one()
+        print("Selected hero:")
+        print(selected_hero)
+        print("Selected hero ID:")
+        print(selected_hero.id)
+
+
+def main() -> None:
+    create_db_and_tables()
+    create_hero()
+    select_hero()
+
+
+if __name__ == "__main__":
+    main()

docs_src/advanced/uuid/tutorial001_py310.py

@@ -0,0 +1,64 @@
+import uuid
+
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+
+class Hero(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+
+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_hero():
+    with Session(engine) as session:
+        hero = Hero(name="Deadpond", secret_name="Dive Wilson")
+        print("The hero before saving in the DB")
+        print(hero)
+        print("The hero ID was already set")
+        print(hero.id)
+        session.add(hero)
+        session.commit()
+        session.refresh(hero)
+        print("After saving in the DB")
+        print(hero)
+
+
+def select_hero():
+    with Session(engine) as session:
+        hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_2)
+        session.commit()
+        session.refresh(hero_2)
+        hero_id = hero_2.id
+        print("Created hero:")
+        print(hero_2)
+        print("Created hero ID:")
+        print(hero_id)
+
+        statement = select(Hero).where(Hero.id == hero_id)
+        selected_hero = session.exec(statement).one()
+        print("Selected hero:")
+        print(selected_hero)
+        print("Selected hero ID:")
+        print(selected_hero.id)
+
+
+def main() -> None:
+    create_db_and_tables()
+    create_hero()
+    select_hero()
+
+
+if __name__ == "__main__":
+    main()

docs_src/advanced/uuid/tutorial002.py

@@ -0,0 +1,64 @@
+import uuid
+from typing import Union
+
+from sqlmodel import Field, Session, SQLModel, create_engine
+
+
+class Hero(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: Union[int, None] = Field(default=None, index=True)
+
+
+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_hero():
+    with Session(engine) as session:
+        hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+        print("The hero before saving in the DB")
+        print(hero_1)
+        print("The hero ID was already set")
+        print(hero_1.id)
+        session.add(hero_1)
+        session.commit()
+        session.refresh(hero_1)
+        print("After saving in the DB")
+        print(hero_1)
+
+
+def select_hero():
+    with Session(engine) as session:
+        hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_2)
+        session.commit()
+        session.refresh(hero_2)
+        hero_id = hero_2.id
+        print("Created hero:")
+        print(hero_2)
+        print("Created hero ID:")
+        print(hero_id)
+
+        selected_hero = session.get(Hero, hero_id)
+        print("Selected hero:")
+        print(selected_hero)
+        print("Selected hero ID:")
+        print(selected_hero.id)
+
+
+def main() -> None:
+    create_db_and_tables()
+    create_hero()
+    select_hero()
+
+
+if __name__ == "__main__":
+    main()

docs_src/advanced/uuid/tutorial002_py310.py

@@ -0,0 +1,63 @@
+import uuid
+
+from sqlmodel import Field, Session, SQLModel, create_engine
+
+
+class Hero(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+
+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_hero():
+    with Session(engine) as session:
+        hero = Hero(name="Deadpond", secret_name="Dive Wilson")
+        print("The hero before saving in the DB")
+        print(hero)
+        print("The hero ID was already set")
+        print(hero.id)
+        session.add(hero)
+        session.commit()
+        session.refresh(hero)
+        print("After saving in the DB")
+        print(hero)
+
+
+def select_hero():
+    with Session(engine) as session:
+        hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_2)
+        session.commit()
+        session.refresh(hero_2)
+        hero_id = hero_2.id
+        print("Created hero:")
+        print(hero_2)
+        print("Created hero ID:")
+        print(hero_id)
+
+        selected_hero = session.get(Hero, hero_id)
+        print("Selected hero:")
+        print(selected_hero)
+        print("Selected hero ID:")
+        print(selected_hero.id)
+
+
+def main() -> None:
+    create_db_and_tables()
+    create_hero()
+    select_hero()
+
+
+if __name__ == "__main__":
+    main()

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
@@ -99,6 +100,7 @@ nav:
   - Advanced User Guide:
     - advanced/index.md
     - advanced/decimal.md
+    - advanced/uuid.md
   - alternatives.md
   - help.md
   - contributing.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.19"
+__version__ = "0.0.21"
 
 # Re-export from SQLAlchemy
 from sqlalchemy.engine import create_engine as create_engine
@@ -140,5 +140,4 @@ from .sql.expression import select as select
 from .sql.expression import tuple_ as tuple_
 from .sql.expression import type_coerce as type_coerce
 from .sql.expression import within_group as within_group
-from .sql.sqltypes import GUID as GUID
 from .sql.sqltypes import AutoString as AutoString

sqlmodel/_compat.py

@@ -194,7 +194,7 @@ if IS_PYDANTIC_V2:
             # Non optional unions are not allowed
             if bases[0] is not NoneType and bases[1] is not NoneType:
                 raise ValueError(
-                    "Cannot have a (non-optional) union as a SQLlchemy field"
+                    "Cannot have a (non-optional) union as a SQLAlchemy field"
                 )
             # Optional unions are allowed
             return bases[0] if bases[0] is not NoneType else bases[1]

sqlmodel/main.py

@@ -51,7 +51,7 @@ from sqlalchemy.orm.attributes import set_attribute
 from sqlalchemy.orm.decl_api import DeclarativeMeta
 from sqlalchemy.orm.instrumentation import is_instrumented
 from sqlalchemy.sql.schema import MetaData
-from sqlalchemy.sql.sqltypes import LargeBinary, Time
+from sqlalchemy.sql.sqltypes import LargeBinary, Time, Uuid
 from typing_extensions import Literal, deprecated, get_origin
 
 from ._compat import (  # type: ignore[attr-defined]
@@ -80,7 +80,7 @@ from ._compat import (  # type: ignore[attr-defined]
     sqlmodel_init,
     sqlmodel_validate,
 )
-from .sql.sqltypes import GUID, AutoString
+from .sql.sqltypes import AutoString
 
 if TYPE_CHECKING:
     from pydantic._internal._model_construction import ModelMetaclass as ModelMetaclass
@@ -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
@@ -608,7 +693,7 @@ def get_sqlalchemy_type(field: Any) -> Any:
             scale=getattr(metadata, "decimal_places", None),
         )
     if issubclass(type_, uuid.UUID):
-        return GUID
+        return Uuid
     raise ValueError(f"{type_} has no matching SQLAlchemy type")
 
 
@@ -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,

sqlmodel/sql/sqltypes.py

@@ -1,10 +1,7 @@
-import uuid
-from typing import Any, Optional, cast
+from typing import Any, cast
 
-from sqlalchemy import CHAR, types
-from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy import types
 from sqlalchemy.engine.interfaces import Dialect
-from sqlalchemy.sql.type_api import TypeEngine
 
 
 class AutoString(types.TypeDecorator):  # type: ignore
@@ -17,43 +14,3 @@ class AutoString(types.TypeDecorator):  # type: ignore
         if impl.length is None and dialect.name == "mysql":
             return dialect.type_descriptor(types.String(self.mysql_default_length))
         return super().load_dialect_impl(dialect)
-
-
-# Reference form SQLAlchemy docs: https://docs.sqlalchemy.org/en/14/core/custom_types.html#backend-agnostic-guid-type
-# with small modifications
-class GUID(types.TypeDecorator):  # type: ignore
-    """Platform-independent GUID type.
-
-    Uses PostgreSQL's UUID type, otherwise uses
-    CHAR(32), storing as stringified hex values.
-
-    """
-
-    impl = CHAR
-    cache_ok = True
-
-    def load_dialect_impl(self, dialect: Dialect) -> TypeEngine[Any]:
-        if dialect.name == "postgresql":
-            return dialect.type_descriptor(UUID())
-        else:
-            return dialect.type_descriptor(CHAR(32))
-
-    def process_bind_param(self, value: Any, dialect: Dialect) -> Optional[str]:
-        if value is None:
-            return value
-        elif dialect.name == "postgresql":
-            return str(value)
-        else:
-            if not isinstance(value, uuid.UUID):
-                return uuid.UUID(value).hex
-            else:
-                # hexstring
-                return value.hex
-
-    def process_result_value(self, value: Any, dialect: Dialect) -> Optional[uuid.UUID]:
-        if value is None:
-            return value
-        else:
-            if not isinstance(value, uuid.UUID):
-                value = uuid.UUID(value)
-            return cast(uuid.UUID, value)

tests/test_advanced/test_uuid/test_tutorial001.py

@@ -0,0 +1,71 @@
+from unittest.mock import patch
+
+from dirty_equals import IsUUID
+from sqlmodel import create_engine
+
+from ...conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel) -> None:
+    from docs_src.advanced.uuid 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()
+    first_uuid = calls[1][0]["id"]
+    assert first_uuid == IsUUID(4)
+
+    second_uuid = calls[7][0]["id"]
+    assert second_uuid == IsUUID(4)
+
+    assert first_uuid != second_uuid
+
+    assert calls == [
+        ["The hero before saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "id": first_uuid,
+                "age": None,
+            }
+        ],
+        ["The hero ID was already set"],
+        [first_uuid],
+        ["After saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "age": None,
+                "id": first_uuid,
+            }
+        ],
+        ["Created hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Created hero ID:"],
+        [second_uuid],
+        ["Selected hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Selected hero ID:"],
+        [second_uuid],
+    ]

tests/test_advanced/test_uuid/test_tutorial001_py310.py

@@ -0,0 +1,72 @@
+from unittest.mock import patch
+
+from dirty_equals import IsUUID
+from sqlmodel import create_engine
+
+from ...conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel) -> None:
+    from docs_src.advanced.uuid 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()
+    first_uuid = calls[1][0]["id"]
+    assert first_uuid == IsUUID(4)
+
+    second_uuid = calls[7][0]["id"]
+    assert second_uuid == IsUUID(4)
+
+    assert first_uuid != second_uuid
+
+    assert calls == [
+        ["The hero before saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "id": first_uuid,
+                "age": None,
+            }
+        ],
+        ["The hero ID was already set"],
+        [first_uuid],
+        ["After saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "age": None,
+                "id": first_uuid,
+            }
+        ],
+        ["Created hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Created hero ID:"],
+        [second_uuid],
+        ["Selected hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Selected hero ID:"],
+        [second_uuid],
+    ]

tests/test_advanced/test_uuid/test_tutorial002.py

@@ -0,0 +1,71 @@
+from unittest.mock import patch
+
+from dirty_equals import IsUUID
+from sqlmodel import create_engine
+
+from ...conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel) -> None:
+    from docs_src.advanced.uuid 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()
+    first_uuid = calls[1][0]["id"]
+    assert first_uuid == IsUUID(4)
+
+    second_uuid = calls[7][0]["id"]
+    assert second_uuid == IsUUID(4)
+
+    assert first_uuid != second_uuid
+
+    assert calls == [
+        ["The hero before saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "id": first_uuid,
+                "age": None,
+            }
+        ],
+        ["The hero ID was already set"],
+        [first_uuid],
+        ["After saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "age": None,
+                "id": first_uuid,
+            }
+        ],
+        ["Created hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Created hero ID:"],
+        [second_uuid],
+        ["Selected hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Selected hero ID:"],
+        [second_uuid],
+    ]

tests/test_advanced/test_uuid/test_tutorial002_py310.py

@@ -0,0 +1,72 @@
+from unittest.mock import patch
+
+from dirty_equals import IsUUID
+from sqlmodel import create_engine
+
+from ...conftest import get_testing_print_function, needs_py310
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel) -> None:
+    from docs_src.advanced.uuid 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()
+    first_uuid = calls[1][0]["id"]
+    assert first_uuid == IsUUID(4)
+
+    second_uuid = calls[7][0]["id"]
+    assert second_uuid == IsUUID(4)
+
+    assert first_uuid != second_uuid
+
+    assert calls == [
+        ["The hero before saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "id": first_uuid,
+                "age": None,
+            }
+        ],
+        ["The hero ID was already set"],
+        [first_uuid],
+        ["After saving in the DB"],
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "age": None,
+                "id": first_uuid,
+            }
+        ],
+        ["Created hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Created hero ID:"],
+        [second_uuid],
+        ["Selected hero:"],
+        [
+            {
+                "name": "Spider-Boy",
+                "secret_name": "Pedro Parqueador",
+                "age": None,
+                "id": second_uuid,
+            }
+        ],
+        ["Selected hero ID:"],
+        [second_uuid],
+    ]

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,
+            },
+        ],
+    ]