Merge branch 'main' into main

Author: tiangolo

.github/dependabot.yml

@@ -1,5 +1,11 @@
 version: 2
 updates:
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+  # Python
   - package-ecosystem: "pip"
     directory: "/"
     schedule:

.github/workflows/build-docs.yml

@@ -1,6 +1,8 @@
 name: Build Docs
 on:
   push:
+    branches:
+      - main
   pull_request:
     types: [opened, synchronize]
   workflow_dispatch:
@@ -51,8 +53,16 @@ jobs:
       - name: Install Material for MkDocs Insiders
         if: github.event.pull_request.head.repo.fork == false && steps.cache.outputs.cache-hit != 'true'
         run: python -m poetry run pip install git+https://${{ secrets.ACTIONS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
+      - uses: actions/cache@v2
+        with:
+          key: mkdocs-cards-${{ github.ref }}
+          path: .cache
       - name: Build Docs
+        if: github.event.pull_request.head.repo.fork == true
         run: python -m poetry run mkdocs build
+      - name: Build Docs with Insiders
+        if: github.event.pull_request.head.repo.fork == false
+        run: python -m poetry run mkdocs build --config-file mkdocs.insiders.yml
       - name: Zip docs
         run: python -m poetry run bash ./scripts/zip-docs.sh
       - uses: actions/upload-artifact@v2

.github/workflows/test.yml

@@ -2,6 +2,8 @@ name: Test
 
 on:
   push:
+    branches:
+      - main
   pull_request:
     types: [opened, synchronize]
   workflow_dispatch:
@@ -16,7 +18,7 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.6.15", "3.7", "3.8", "3.9", "3.10"]
       fail-fast: false
 
     steps:
@@ -52,9 +54,9 @@ jobs:
         if: steps.cache.outputs.cache-hit != 'true'
         run: python -m poetry install
       - name: Lint
-        if: ${{ matrix.python-version != '3.6' }}
+        if: ${{ matrix.python-version != '3.6.15' }}
         run: python -m poetry run bash scripts/lint.sh
       - name: Test
         run: python -m poetry run bash scripts/test.sh
       - name: Upload coverage
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v2

.gitignore

@@ -11,3 +11,4 @@ htmlcov
 coverage.xml
 site
 *.db
+.cache

README.md

@@ -212,4 +212,4 @@ And at the same time, ✨ it is also a **Pydantic** model ✨. You can use inher
 
 ## License
 
-This project is licensed under the terms of the MIT license.
+This project is licensed under the terms of the [MIT license](https://github.com/tiangolo/sqlmodel/blob/main/LICENSE).

docs/advanced/decimal.md

@@ -0,0 +1,148 @@
+# Decimal Numbers
+
+In some cases you might need to be able to store decimal numbers with guarantees about the precision.
+
+This is particularly important if you are storing things like **currencies**, **prices**, **accounts**, and others, as you would want to know that you wouldn't have rounding errors.
+
+As an example, if you open Python and sum `1.1` + `2.2` you would expect to see `3.3`, but you will actually get `3.3000000000000003`:
+
+```Python
+>>> 1.1 + 2.2
+3.3000000000000003
+```
+
+This is because of the way numbers are stored in "ones and zeros" (binary). But Python has a module and some types to have strict decimal values. You can read more about it in the official <a href="https://docs.python.org/3/library/decimal.html" class="external-link" target="_blank">Python docs for Decimal</a>.
+
+Because databases store data in the same ways as computers (in binary), they would have the same types of issues. And because of that, they also have a special **decimal** type.
+
+In most cases this would probably not be a problem, for example measuring views in a video, or the life bar in a videogame. But as you can imagine, this is particularly important when dealing with **money** and **finances**.
+
+## Decimal Types
+
+Pydantic has special support for `Decimal` types using the <a href="https://pydantic-docs.helpmanual.io/usage/types/#arguments-to-condecimal" class="external-link" target="_blank">`condecimal()` special function</a>.
+
+!!! tip
+    Pydantic 1.9, that will be released soon, has improved support for `Decimal` types, without needing to use the `condecimal()` function.
+
+    But meanwhile, you can already use this feature with `condecimal()` in **SQLModel** it as it's explained here.
+
+When you use `condecimal()` you can specify the number of digits and decimal places to support. They will be validated by Pydantic (for example when using FastAPI) and the same information will also be used for the database columns.
+
+!!! info
+    For the database, **SQLModel** will use <a href="https://docs.sqlalchemy.org/en/14/core/type_basics.html#sqlalchemy.types.DECIMAL" class="external-link" target="_blank">SQLAlchemy's `DECIMAL` type</a>.
+
+## Decimals in SQLModel
+
+Let's say that each hero in the database will have an amount of money. We could make that field a `Decimal` type using the `condecimal()` function:
+
+```{.python .annotate hl_lines="12" }
+{!./docs_src/advanced/decimal/tutorial001.py[ln:1-12]!}
+
+# More code here later 👇
+```
+
+<details>
+<summary>👀 Full file preview</summary>
+
+```Python
+{!./docs_src/advanced/decimal/tutorial001.py!}
+```
+
+</details>
+
+Here we are saying that `money` can have at most `5` digits with `max_digits`, **this includes the integers** (to the left of the decimal dot) **and the decimals** (to the right of the decimal dot).
+
+We are also saying that the number of decimal places (to the right of the decimal dot) is `3`, so we can have **3 decimal digits** for these numbers in the `money` field. This means that we will have **2 digits for the integer part** and **3 digits for the decimal part**.
+
+✅ So, for example, these are all valid numbers for the `money` field:
+
+* `12.345`
+* `12.3`
+* `12`
+* `1.2`
+* `0.123`
+* `0`
+
+🚫 But these are all invalid numbers for that `money` field:
+
+* `1.2345`
+    * This number has more than 3 decimal places.
+* `123.234`
+    * This number has more than 5 digits in total (integer and decimal part).
+* `123`
+    * Even though this number doesn't have any decimals, we still have 3 places saved for them, which means that we can **only use 2 places** for the **integer part**, and this number has 3 integer digits. So, the allowed number of integer digits is `max_digits` - `decimal_places` = 2.
+
+!!! tip
+    Make sure you adjust the number of digits and decimal places for your own needs, in your own application. 🤓
+
+## Create models with Decimals
+
+When creating new models you can actually pass normal (`float`) numbers, Pydantic will automatically convert them to `Decimal` types, and **SQLModel** will store them as `Decimal` types in the database (using SQLAlchemy).
+
+```Python hl_lines="4-6"
+# Code above omitted 👆
+
+{!./docs_src/advanced/decimal/tutorial001.py[ln:25-35]!}
+
+# Code below omitted 👇
+```
+
+<details>
+<summary>👀 Full file preview</summary>
+
+```Python
+{!./docs_src/advanced/decimal/tutorial001.py!}
+```
+
+</details>
+
+## Select Decimal data
+
+Then, when working with Decimal types, you can confirm that they indeed avoid those rounding errors from floats:
+
+```Python hl_lines="15-16"
+# Code above omitted 👆
+
+{!./docs_src/advanced/decimal/tutorial001.py[ln:38-51]!}
+
+# Code below omitted 👇
+```
+
+<details>
+<summary>👀 Full file preview</summary>
+
+```Python
+{!./docs_src/advanced/decimal/tutorial001.py!}
+```
+
+</details>
+
+## Review the results
+
+Now if you run this, instead of printing the unexpected number `3.3000000000000003`, it prints `3.300`:
+
+<div class="termy">
+
+```console
+$ python app.py
+
+// Some boilerplate and previous output omitted 😉
+
+// The type of money is Decimal('1.100')
+Hero 1: id=1 secret_name='Dive Wilson' age=None name='Deadpond' money=Decimal('1.100')
+
+// More output omitted here 🤓
+
+// The type of money is Decimal('1.100')
+Hero 2: id=3 secret_name='Tommy Sharp' age=48 name='Rusty-Man' money=Decimal('2.200')
+
+// No rounding errors, just 3.3! 🎉
+Total money: 3.300
+```
+
+</div>
+
+!!! warning
+    Although Decimal types are supported and used in the Python side, not all databases support it. In particular, SQLite doesn't support decimals, so it will convert them to the same floating `NUMERIC` type it supports.
+
+    But decimals are supported by most of the other SQL databases. 🎉

docs/advanced/index.md

@@ -1,12 +1,10 @@
 # Advanced User Guide
 
-The **Advanced User Guide** will be coming soon to a <del>theater</del> **documentation** near you... 😅
+The **Advanced User Guide** is gradually growing, you can already read about some advanced topics.
 
-I just have to `add` it, `commit` it, and `refresh` it. 😉
+At some point it will include:
 
-It will include:
-
-* How to use the `async` and `await` with the async session.
+* How to use `async` and `await` with the async session.
 * How to run migrations.
 * How to combine **SQLModel** models with SQLAlchemy.
-* ...and more.
+* ...and more. 🤓

docs/contributing.md

@@ -42,7 +42,7 @@ $ poetry shell
 
 </div>
 
-That will set up the environment variables needed dand will start a new shell with them.
+That will set up the environment variables needed and start a new shell with them.
 
 #### Using your local SQLModel
 

docs/databases.md

@@ -85,7 +85,7 @@ Some examples of databases that work like this could be **PostgreSQL**, **MySQL*
 
 ### Distributed servers
 
-In some cases, the database could even be a group server applications running on different machines, working together and communicating between them to be more efficient and handle more data.
+In some cases, the database could even be a group of server applications running on different machines, working together and communicating between them to be more efficient and handle more data.
 
 In this case, your code would talk to one or more of these server applications running on different machines.
 
@@ -250,7 +250,7 @@ As these **primary key** IDs can uniquely identify each row on the table for tea
 
 <img alt="table relationships" src="/img/databases/relationships.svg">
 
-So, in the table for heroes, we use the `team_id` column to define a relationship to the *foreign* table for teams. Each value in the `team_id` column on the table with heroes will be the same value as the `id` column of one row in the table wiwth teams.
+So, in the table for heroes, we use the `team_id` column to define a relationship to the *foreign* table for teams. Each value in the `team_id` column on the table with heroes will be the same value as the `id` column of one row in the table with teams.
 
 In the table for heroes we have a **primary key** that is the `id`. But we also have another column `team_id` that refers to a **key** in a **foreign** table. There's a technical term for that too, the `team_id` is a "**foreign key**".
 
@@ -274,7 +274,7 @@ The language is called **SQL**, the name comes from for **Structured Query Langu
 
 Nevertheless, the language is not only used to *query* for data. It is also used to create records/rows, to update them, to delete them. And to manipulate the database, create tables, etc.
 
-This language is supported by all these databases that handle multiple tables, that's why they are called **SQL Databases**. Although, each database has small variations in the SQL language they support.
+This language is supported by all these databases that handle multiple tables, that's why they are called **SQL Databases**. Although, each database has small variations in the SQL language they support (*dialect*).
 
 Let's imagine that the table holding the heroes is called the `hero` table. An example of a SQL query to get all the data from it could look like:
 

docs/db-to-code.md

@@ -143,7 +143,7 @@ If the user provides this ID:
 2
 ```
 
-...the  would be this table (with a single row):
+...the result would be this table (with a single row):
 
 <table>
 <tr>

docs/help.md

@@ -12,7 +12,7 @@ And there are several ways to get help too.
 
 ## Subscribe to the FastAPI and Friends newsletter
 
-You can subscribe to the (infrequent) [**FastAPI and friends** newsletter](/newsletter/){.internal-link target=_blank} to stay updated about:
+You can subscribe to the (infrequent) <a href="https://fastapi.tiangolo.com/newsletter" class="external-link" target="_blank">**FastAPI and friends** newsletter</a> to stay updated about:
 
 * News about FastAPI and friends, including SQLModel 🚀
 * Guides 📝