在 FastAPI 項目中，Tortoise-ORM 是一個輕量的異步 ORM 框架，適用于 async/await 場景。結合數據庫遷移工具 Aerich，可以優雅地管理數據庫表結構演進，本文將通過完整流程演示如何在 MySQL 環境下使用。

---

📦 一、環境準備

確保已經安裝如下依賴：

pip install fastapi tortoise-orm aerich asyncmy

• tortoise-orm：異步 ORM 框架
• aerich：Tortoise-ORM 的遷移管理工具
• asyncmy：Tortoise 連接 MySQL 所用的異步驅動（也可用 aiomysql）

---

? 二、Tortoise 配置 settings.py

創建 settings.py，配置 Tortoise-ORM 連接和應用模塊：

TORTOISE_ORM = {"connections": {"default": {"engine": "tortoise.backends.mysql","credentials": {"host": "127.0.0.1","port": 3306,"user": "root","password": "your_password","database": "fastapi","minsize": 1,"maxsize": 5,"charset": "utf8mb4","echo": True},}},"apps": {"models": {"models": ["models", "aerich.models"],  # 注冊你的模型模塊和 aerich 內置模型"default_connection": "default",}},"use_tz": False,"timezone": "Asia/Shanghai",
}

---

🛠? 三、Aerich 初始化和數據庫初始化

1?? 初始化 Aerich 項目

aerich init -t settings.TORTOISE_ORM

• -t 參數傳入 Tortoise 配置變量路徑
• 自動生成 pyproject.toml 和 migrations/ 目錄

2?? 初始化數據庫

aerich init-db

會根據當前模型自動創建表，并生成初始遷移文件：

Success creating app migration folder migrations\models
Success generating initial migration file for app "models"

---

🔁 四、模型修改與遷移管理

?? 1. 修改模型

如果需要在 models.py 中添加字段或改動模型：

from tortoise.models import Model
from tortoise import fieldsclass User(Model):id = fields.IntField(pk=True)username = fields.CharField(max_length=50)age = fields.IntField(null=True)  # 新增字段

🔄 2. 生成遷移文件

aerich migrate

輸出示例：

Success creating migration file 1_20250706114908_update.py

?? 3. 升級數據庫

aerich upgrade

應用最新遷移，更新數據庫結構：

Success upgrading to 1_20250706114908_update.py

---

?? 五、回滾與歷史查看

?? 回滾上一次遷移（危險操作）

aerich downgrade

需要確認是否繼續，謹慎操作：

Downgrade is dangerous: you might lose your data! Are you sure? [y/N]: y

📜 查看遷移歷史

aerich history

輸出：

0_20250706114346_init.py
1_20250706114908_update.py

---

? 總結：常用 Aerich 命令表

命令	說明
aerich init -t settings.TORTOISE_ORM	初始化 Aerich 項目
aerich init-db	初始化數據庫并創建初始遷移
aerich migrate	根據模型變更生成遷移文件
aerich upgrade	執行遷移，更新數據庫結構
aerich downgrade	回滾上一個遷移版本
aerich history	查看所有遷移歷史版本

---

🧩 參考項目結構

FastapiProject/
├── app/
│   └── models.py
├── settings.py
├── main.py
├── migrations/
│   └── models/
├── pyproject.toml

---

🚀 寫在最后

使用 Aerich + Tortoise-ORM，可以極大地簡化異步 FastAPI 項目的數據庫遷移管理過程。尤其在協作開發、版本迭代中，結構化的遷移記錄將為數據庫演進提供可追溯性與安全性。

如果要集成 SQLite 或 PostgreSQL，只需要調整 db_url 或 engine 和驅動包即可。