当前位置: 首页 > news >正文

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.tomlmigrations/ 目录

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

http://www.lryc.cn/news/581690.html

相关文章:

  • 深度学习 必然用到的 线性代数知识
  • 嵌入式 数据结构学习(五) 栈与队列的实现与应用
  • React Ref 指南:原理、实现与实践
  • 【PyTorch】PyTorch中torch.nn模块的卷积层
  • 零基础,使用Idea工具写一个邮件报警程序
  • Solidity——什么是状态变量
  • 计算机网络:(七)网络层(上)网络层中重要的概念与网际协议 IP
  • Kafka “假死“现象深度解析与解决方案
  • UI前端大数据可视化进阶:交互式仪表盘的设计与应用
  • 数据驱动实时市场动态监测:让商业决策跑赢时间
  • 【LeetCode 热题 100】240. 搜索二维矩阵 II——排除法
  • 黑马点评系列问题之实战篇02短信登录 利用资料中的mysql语句创建数据表时报错
  • 关于 栈帧变化完整流程图(函数嵌套)
  • Java 双亲委派机制笔记
  • QML 使用QtObject定义私有变量
  • 基于Flask和机器学习开发的米其林餐厅数据可视化平台
  • 单片机:STM32F103的开发环境搭建
  • 单片机物联网应用中的 Pogopin、串口与外围模组通信技术解析
  • ABP VNext + Tye:本地微服务编排与调试
  • 基于udev规则固定相机名称
  • [netty5: WebSocketServerHandshaker WebSocketServerHandshakerFactory]-源码分析
  • 桥梁桥拱巡检机器人cad+【4张】设计说明书+绛重+三维图
  • 力扣 hot100 Day36
  • webUI平替应用,安装简单,功能齐全
  • LeetCode 75. 颜色分类(荷兰国旗问题)
  • 服务端向客户端主动推送数据的几种方法(Spring Boot 环境)
  • 11.进程间通信
  • VSCode+arm-none-eabi-gcc交叉编译+CMake构建+OpenOCD(基于Raspberry Pico RP2040)
  • 2.线性神经网络--Softmax回归
  • 算法分析与设计实验1:实现两路合并排序和折半插入排序