python/sqlmodel
1
0
Fork 0
mirror of https://github.com/fastapi/sqlmodel.git synced 2025-08-14 17:41:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

📝 Update all docs references to Optional to use the new syntax in Python 3.10, e.g. int | None (#1351)

Browse Source
This commit is contained in:
Sebastián Ramírez
2025-04-27 20:53:37 +02:00
committed by GitHub
parent 0e5e19773c
commit 61523864f1
15 changed files with 52 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/tutorial/create-db-and-table.md
View File

@ -67,11 +67,9 @@ And the type of each of them will also be the type of table column:
Let's now see with more detail these field/column declarations.
### Optional Fields, Nullable Columns
### `None` Fields, Nullable Columns
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.
Let's start with `age`, notice that it has a type of `int | None`.
That is the standard way to declare that something "could be an `int` or `None`" in Python.
@ -81,21 +79,23 @@ And we also set the default value of `age` to `None`.
/// tip
We also define `id` with `Optional`. But we will talk about `id` below.
We also define `id` with `int | None`. But we will talk about `id` below.
///
This way, we tell **SQLModel** that `age` is not required when validating data and that it has a default value of `None`.
Because the type is `int | None`:
And we also tell it that, in the SQL database, the default value of `age` is `NULL` (the SQL equivalent to Python's `None`).
* When validating data, `None` will be an allowed value for `age`.
* In the database, the column for `age` will be allowed to have `NULL` (the SQL equivalent to Python's `None`).
So, this column is "nullable" (can be set to `NULL`).
And because there's a default value `= None`:
/// info
* When validating data, this `age` field won't be required, it will be `None` by default.
* When saving to the database, the `age` column will have a `NULL` value by default.
In terms of **Pydantic**, `age` is an **optional field**.
/// tip
In terms of **SQLAlchemy**, `age` is a **nullable column**.
The default value could have been something else, like `= 42`.
///
@ -111,7 +111,7 @@ To do that, we use the special `Field` function from `sqlmodel` and set the argu
That way, we tell **SQLModel** that this `id` field/column is the primary key of the table.
But inside the SQL database, it is **always required** and can't be `NULL`. Why should we declare it with `Optional`?
But inside the SQL database, it is **always required** and can't be `NULL`. Why should we declare it with `int | None`?
The `id` will be required in the database, but it will be *generated by the database*, not by our code.
@ -128,7 +128,7 @@ somehow_save_in_db(my_hero)
do_something(my_hero.id) # Now my_hero.id has a value generated in DB 🎉
```
So, because in *our code* (not in the database) the value of `id` *could be* `None`, we use `Optional`. This way **the editor will be able to help us**, for example, if we try to access the `id` of an object that we haven't saved in the database yet and would still be `None`.
So, because in *our code* (not in the database) the value of `id` *could be* `None`, we use `int | None`. This way **the editor will be able to help us**, for example, if we try to access the `id` of an object that we haven't saved in the database yet and would still be `None`.
<img class="shadow" src="/img/create-db-and-table/inline-errors01.png">