Aerich实战指南：零基础掌握异步ORM数据库迁移工具

在Python异步编程的浪潮中，数据库迁移工具的选择直接影响开发效率与工程规范性。Aerich作为Tortoise ORM的官方迁移工具，以简洁的命令行操作和强大的自动化能力，成为异步开发者不可或缺的利器。本文将从零开始，通过一个博客系统的实战案例，手把手教你掌握Aerich的核心用法。

---

一、环境准备与安装

1. 安装依赖库

Aerich需要与Tortoise ORM配合使用。通过以下命令安装核心库：

pip install tortoise-orm aerich

若使用MySQL或PostgreSQL，需额外安装驱动：

pip install aiomysql    # MySQL
pip install asyncpg     # PostgreSQL

2. 项目结构规划

建议按以下结构组织代码，便于维护：

blog_project/
├── config.py           # 数据库配置
├── models.py           # 数据模型
└── migrations/         # 迁移文件（自动生成）

---

二、配置数据库连接

在config.py中定义Tortoise ORM配置（以SQLite为例）：

# config.py
TORTOISE_ORM = {"connections": {"default": "sqlite://blog.db"  # SQLite文件路径},"apps": {"blog_app": {"models": ["models", "aerich.models"],  # 模型文件路径"default_connection": "default",}}
}

• 关键点：aerich.models必须包含，用于生成迁移记录表。

---

三、初始化迁移环境

1. 初始化Aerich配置

执行命令生成迁移目录和配置文件：

aerich init -t config.TORTOISE_ORM

输出提示生成migrations目录和pyproject.toml文件，后者记录配置路径。

2. 创建初始数据库

生成数据库文件及aerich表：

aerich init-db

此时数据库中将创建aerich表用于记录迁移历史。

---

四、模型定义与迁移操作

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, unique=True)created_at = fields.DatetimeField(auto_now_add=True)

2. 生成迁移文件

检测模型变化并生成迁移脚本：

aerich migrate --name create_user_table

在migrations目录下生成类似20250420_1234_create_user_table.sql的文件。

3. 应用迁移至数据库

执行迁移脚本：

aerich upgrade

此时数据库中自动创建user表。

---

五、模型变更与增量迁移

1. 修改模型添加字段

在User模型中新增email字段：

class User(Model):# ...原有字段email = fields.CharField(max_length=100, null=True)  # 新增字段

2. 生成并应用新迁移

aerich migrate --name add_email_field
aerich upgrade

数据库user表将新增email列。

---

六、实战案例：博客系统建模

1. 完整模型设计

在models.py中扩展模型：

class Post(Model):id = fields.IntField(pk=True)title = fields.CharField(max_length=200)content = fields.TextField()author = fields.ForeignKeyField("models.User", related_name="posts")published = fields.BooleanField(default=False)class Comment(Model):id = fields.IntField(pk=True)content = fields.TextField()post = fields.ForeignKeyField("models.Post", related_name="comments")user = fields.ForeignKeyField("models.User", related_name="comments")

2. 批量生成迁移

aerich migrate --name create_blog_models
aerich upgrade

数据库中将自动创建post和comment表，并建立外键关联。

---

七、高级功能实践

1. 回滚迁移

撤销最后一次变更：

aerich downgrade

回退到add_email_field版本，email字段将被删除。

2. 查看迁移历史

aerich history

输出示例：

[✓] 20250420_1234_create_user_table
[✓] 20250420_1345_add_email_field
[ ] 20250420_1400_create_blog_models

3. 从数据库逆向生成模型

若已有数据库表，生成对应模型：

aerich inspectdb > models_legacy.py

自动生成包含表结构的Python模型类。

---

八、生产环境最佳实践

1. 多数据库配置

在config.py中配置主从数据库：

TORTOISE_ORM = {"connections": {"master": "mysql://root:pass@master/db","replica": "mysql://root:pass@replica/db"},"apps": {"blog_app": {"models": ["models", "aerich.models"],"default_connection": "master",}}
}

2. CI/CD集成

在GitHub Actions中自动执行迁移：

- name: Apply Migrationsrun: |aerich upgrade

---

九、常见问题排查

1. 迁移文件冲突
   多人开发时可能生成重复迁移文件，需手动合并后执行aerich upgrade --fake标记已应用。

2. 字段类型不匹配
   若迁移时报错，检查模型字段类型是否与数据库兼容（如MySQL的Text对应fields.TextField）。

3. 外键约束失败
   确保关联模型已正确定义，并按照依赖顺序执行迁移。

---

十、总结

通过以上步骤，我们完成了从零配置、模型定义、迁移操作到生产优化的完整流程。Aerich的核心价值在于：

• 自动化迁移：通过模型变化自动生成SQL脚本
• 版本可控：迁移文件纳入Git管理，支持团队协作
• 无缝集成：完美适配FastAPI、Sanic等异步框架

掌握Aerich后，开发者可将精力聚焦业务逻辑，告别手动维护数据库结构的低效时代。异步生态的成熟，让Python在高并发场景下的竞争力进一步增强。