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

篮之新喜 · 2025-4-29 23:00:46

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
往期文章归档：

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

		自动登录	找回密码
密码			立即注册

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

本帖子中包含更多资源

0 个回复

快速回复

楼主热帖

标签云