title: FastAPI与Tortoise-ORM模型配置及aerich迁移工具

date: 2025/04/30 00:11:45

updated: 2025/04/30 00:11:45

excerpt:

FastAPI中使用Tortoise-ORM时，模型类通过继承tortoise.models.Model并定义class Meta来映射数据库字段。元数据配置包括表名、schema、表注释和联合唯一约束等。初始化数据库连接推荐使用lifespan事件处理，配置参数包括数据库URL、模型模块路径等。aerich迁移工具用于管理数据库迁移，通过init-db、migrate和upgrade等命令实现迁移文件的生成和应用。常见问题包括模型注册失败和迁移文件冲突，需检查模型路径和清除冲突文件。

categories:

后端开发
FastAPI

tags:

FastAPI
Tortoise-ORM
数据库迁移
aerich工具
模型元数据
数据库初始化
常见问题解决方案

扫描二维码

关注或者微信搜一搜：编程智域前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

第一章：模型类元数据配置基础

1.1 模型定义与元数据

在FastAPI中使用Tortoise-ORM时，模型类通过Python类属性与数据库字段建立映射关系。每个模型类必须继承自tortoise.models.Model

，并通过class Meta定义元数据：

python 复制代码

from tortoise.models import Model
from tortoise import fields


class User(Model):
    id = fields.IntField(pk=True)
    username = fields.CharField(max_length=50, unique=True)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "auth_users"
        table_description = "系统用户数据表"
        schema = "public"
        unique_together = (("username", "email"),)

代码解析：

table：指定物理表名称（默认使用类名小写）
schema：数据库schema（适用于PostgreSQL）
table_description：表注释（生成DDL语句时会包含）
unique_together：联合唯一约束

1.2 Tortoise-ORM初始化配置

在FastAPI启动时初始化数据库连接，推荐使用lifespan事件处理：

python 复制代码

from contextlib import asynccontextmanager
from fastapi import FastAPI
from tortoise import Tortoise


@asynccontextmanager
async def lifespan(app: FastAPI):
    await Tortoise.init(
        db_url='postgres://user:pass@localhost:5432/mydb',
        modules={'models': ['app.models']},
        _create_db=True
    )
    await Tortoise.generate_schemas()
    yield
    await Tortoise.close_connections()


app = FastAPI(lifespan=lifespan)

关键参数说明：

modules：指定模型所在模块路径
_create_db：自动创建数据库（仅限开发环境）
generate_schemas：自动生成数据库表结构

第二章：aerich迁移工具实战

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

2.1 aerich安装与初始化

安装命令：

bash 复制代码

pip install aerich

初始化迁移环境：

bash 复制代码

aerich init -t app.config.TORTOISE_ORM
aerich init-db

在项目根目录创建aerich_config.py：

python 复制代码

TORTOISE_ORM = {
    "connections": {"default": "postgres://user:pass@localhost:5432/mydb"},
    "apps": {
        "models": {
            "models": ["app.models", "aerich.models"],
            "default_connection": "default",
        }
    },
}

2.2 迁移操作流程

创建迁移文件：

bash 复制代码

aerich migrate --name add_user_table

查看未应用的迁移：

bash 复制代码

aerich show migrations

执行升级：

bash 复制代码

aerich upgrade

回滚变更：

bash 复制代码

aerich downgrade -v -1

2.3 迁移文件示例

生成的迁移文件migrations/20231111_1200_add_user_table.sql：

sql 复制代码

-- upgrade --
CREATE TABLE "auth_users"
(
    "id"         SERIAL      NOT NULL PRIMARY KEY,
    "username"   VARCHAR(50) NOT NULL UNIQUE,
    "created_at" TIMESTAMP   NOT NULL
);
COMMENT
ON TABLE "auth_users" IS '系统用户数据表';
-- downgrade --
DROP TABLE "auth_users";

第三章：常见问题解决方案

3.1 模型注册失败

错误现象：
tortoise.exceptions.ConfigurationError: No models in config

解决方案：

检查aerich_config.py中的模型路径是否包含实际模型文件
确认__init__.py文件中已导入模型类
确保aerich migrate命令在项目根目录执行

3.2 迁移文件冲突

错误现象：
aerich.exceptions.MigrationConflictError: Duplicate migration version

处理步骤：

删除migrations目录下冲突的迁移文件
清空数据库中的aerich表记录
重新生成迁移文件

课后Quiz

在模型类Meta配置中，table和schema参数有什么区别？
A) table定义逻辑表名，schema定义物理存储位置
B) table定义物理表名，schema定义数据库模式
C) 两者可以互换使用
D) schema用于定义索引结构

答案：B

解析：table参数指定数据库中的实际表名，schema用于定义数据库模式（如PostgreSQL的schema），两者共同决定表的物理存储位置。

使用aerich进行数据库迁移的正确步骤是：
A) init-db → migrate → upgrade
B) migrate → init-db → upgrade
C) upgrade → migrate → init-db
D) init-db → upgrade → migrate

答案：A

解析：正确流程为初始化数据库（init-db）、生成迁移文件（migrate）、应用变更（upgrade）。需先初始化迁移环境才能生成有效的迁移文件。

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：FastAPI与Tortoise-ORM模型配置及aerich迁移工具 | cmdragon's Blog

FastAPI与Tortoise-ORM模型配置及aerich迁移工具

第一章：模型类元数据配置基础

1.1 模型定义与元数据

1.2 Tortoise-ORM初始化配置

第二章：aerich迁移工具实战

2.1 aerich安装与初始化

2.2 迁移操作流程

2.3 迁移文件示例

第三章：常见问题解决方案

3.1 模型注册失败

3.2 迁移文件冲突

课后Quiz

往期文章归档：