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-dbmigrateupgrade等命令实现迁移文件的生成和应用。常见问题包括模型注册失败和迁移文件冲突,需检查模型路径和清除冲突文件。

categories:

  • 后端开发
  • FastAPI

tags:

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

cmdragon_cn.png

扫描二维码 关注或者微信搜一搜:编程智域 前端至全栈交流与成长

探索数千个预构建的 AI 应用,开启你的下一个伟大创意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 应用,开启你的下一个伟大创意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 迁移操作流程

  1. 创建迁移文件:
bash 复制代码
aerich migrate --name add_user_table
  1. 查看未应用的迁移:
bash 复制代码
aerich show migrations
  1. 执行升级:
bash 复制代码
aerich upgrade
  1. 回滚变更:
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

解决方案:

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

3.2 迁移文件冲突

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

处理步骤:

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

课后Quiz

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

答案:B

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

  1. 使用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

往期文章归档:

相关推荐
martinzh44 分钟前
Spring AI 项目介绍
后端
前端付豪1 小时前
20、用 Python + API 打造终端天气预报工具(支持城市查询、天气图标、美化输出🧊
后端·python
爱学习的小学渣1 小时前
关系型数据库
后端
武子康1 小时前
大数据-33 HBase 整体架构 HMaster HRegion
大数据·后端·hbase
前端付豪1 小时前
19、用 Python + OpenAI 构建一个命令行 AI 问答助手
后端·python
凌览1 小时前
斩获 27k Star,一款开源的网站统计工具
前端·javascript·后端
全栈凯哥1 小时前
02.SpringBoot常用Utils工具类详解
java·spring boot·后端
狂师1 小时前
啥是AI Agent!2025年值得推荐入坑AI Agent的五大工具框架!(新手科普篇)
人工智能·后端·程序员
星辰大海的精灵2 小时前
使用Docker和Kubernetes部署机器学习模型
人工智能·后端·架构
MikeWe2 小时前
C++宏的解析:从基础语法到实战场景
后端