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 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
和驱动包即可。