Tortoise ORM / FastAPI 整合快速筆記

因為以往被 Active Record 慣壞了，導致在 Python 圈一直找不到相同順手的 ORM，又因為用的不是像 Django 那樣的大禮包框架，導致我在 ORM 的路上始終尋尋覓覓，今天又又又又又要來介紹另一款 Tortoise ORM。

先吹一波特性：

支援 SQLite、PostgreSQL、MariaDB、MySQL，以及透過 ODBC 支援 SQL Server、Oracle。
異步。
有 migration 機制。
支援多個套件、框架整合，包括 UnitTest、FastAPI、Quart、Sanic、Starlette、aiohttp、BlackSheep、Pydantic，以上有得熱門有得冷門，但奇怪的是竟然沒有 Flask。即便不在上述清單內，只要搞懂 Tortoise 的初始化機制也可以自幹整合。
支援多資料庫。
支援讀寫分離。
但沒有 seeding 機制，得自幹。

下面是 Tortoise 和 FastAPI / pydantic 整合的快速筆記。

定義 Model

這裡的 model 指的是 ORM model，而 pydantic model 則由 ORM model 衍生而來，例如下面這個 models.py：

from tortoise import fields, models
from tortoise.contrib.pydantic import pydantic_model_creator


class Word(models.Model):
    id = fields.IntField(pk=True)
    #: `word` may duplicate, do not have to be unique.
    word = fields.CharField(max_length=255, null=False)
    accent_notation = fields.CharField(max_length=255, null=False)
    
    class Meta:
        table = 'words' # Always name with snake_case


WordRead = pydantic_model_creator(
    cls=Word,
    name='WordRead'
)


WordCreate = pydantic_model_creator(
    cls=Word,
    name='WordCreate',
    exclude_readonly=True  # Exclude `id` on creating
)

這裡我們定義了一個 Word model，旗下欄位由 fields 系列函式定義，應該是可以望文生義。

除欄位定義外，裡面還有一些值得一提的聲明：

word 上面有一行以 #: 開頭的註解，這種格式的註解會變成 pydantic 的 field description，因此也會變成 OpenAPI 的 propertie description。
子類 Meta 的 table 屬性聲明了該 model 的資料表名稱，因為個人習慣在資料表用 snake case，因此就得額外聲明此項囉。

有了 ORM model，後續我們用 pydantic_model_creator() 建立兩個衍生的 pydantic model，習慣上他們的變數名和 model 名會取相同。

最終這份 models.py 有三個成員：

一個 Word ORM model。
一個 WordRead pydantic model。
一個 WordCreate pydantic model，不帶 id 欄位，因為 ID 是資料庫自動產生的，無須用戶提供。

後續我們會在 FastAPI 端點函式中使用到他們。

Tortoise ORM 整合 FastAPI

Tortoise 提供了傻瓜整合機制，自動在 FastAPI 啟動時帶起 Tortoise，結束時關閉 Tortoise 和資料庫的連線。

在 FastAPI 主程式 main.py 如此這般：

from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise

from app.models import WordCreate, Word, WordRead


app: FastAPI = FastAPI()


register_tortoise(
    app=app,
    db_url='sqlite://db.sqlite',
    modules={'models': ['app.models']},
    generate_schemas=True,
    add_exception_handlers=True,
)

那句 register_tortoise() 一行就搞定，它傻瓜你聰明。

在 FastAPI 調用 Tortoise Model

前面定義的三個 model，其中的 Word model 用於實操資料庫，其餘的兩個 model 則用於在 FastAPI 函式中聲明參數或回傳值型態，例如下面這個函式：

@app.post(
    path="/",
    response_model=WordRead,
)
async def create_word(
    word: WordCreate,
):
    new_word: WordRead = await Word.create(
        **word.dict(
            exclude_unset=True,
        )
    )
    return new_word

WordRead 被聲明成回傳的型態、WordCreate 被聲明成參數 word 的型態，而真正實操資料庫的語句則是由 Word.create() 構成，他們之間的轉換由 Tortoise ORM 處理到好。

下面是 CRUD 的另一個例子：

@app.get(
    path='/{word}',
    response_model=list[WordRead],
)
async def get_word(
    word: str
):
    response = await Word.filter(
        word=word
    )
    return response

沿前例類推，WordRead 同樣被聲明成回傳型態，而根據 Word model 的設計，欄位 word 不一定唯一，因此此處調用 Word.filter() 下查詢，回傳的應該是陣列，因此我們將回傳 model 聲明為 list[WordRead]，如果確定查詢只會有單筆紀錄那可以下 Word.get() 做查詢。

結語

本篇是 Tortoise ORM 在 FastAPI 的快速筆記，沒有提到某些也很重要的特性，例如各種花式欄位定義、關聯性、quary API、migration 等等，或許以後有碰到再寫吧，欽此。

定義 Model

Tortoise ORM 整合 FastAPI

在 FastAPI 調用 Tortoise Model

結語

Share