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

title: FastAPI与Tortoise-ORM模型配置及aerich迁移工具
date: 2025/04/30 00:11:45
updated: 2025/04/30 00:11:45
author: cmdragon

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定义元数据：

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事件处理：

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安装与初始化

安装命令：

pip install aerich

初始化迁移环境：

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

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

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

2.2 迁移操作流程

创建迁移文件：

aerich migrate --name add_user_table

查看未应用的迁移：

aerich show migrations

执行升级：

aerich upgrade

回滚变更：

aerich downgrade -v -1

2.3 迁移文件示例

生成的迁移文件migrations/20231111_1200_add_user_table.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