FastAPI + Tortoise-ORM + Aerich 实现数据库迁移管理（MySQL 实践）

在 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 fields

class 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 命令表

🧩 参考项目结构

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

🚀 写在最后

使用 Aerich + Tortoise-ORM，可以极大地简化异步 FastAPI 项目的数据库迁移管理过程。尤其在协作开发、版本迭代中，结构化的迁移记录将为数据库演进提供可追溯性与安全性。

如果要集成 SQLite 或 PostgreSQL，只需要调整 db_url 或 engine 和驱动包即可。