登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 群组 › IT互联网 › 网站 › 程序园子 ›FastAPI与Tortoise-ORM模型配置及aerich迁移工具 ...

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

汲佩杉 2025-5-29 01:54:19
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工具
  • 模型元数据
  • 数据库初始化
  • 常见问题解决方案
1.jpeg
2.jpg
扫描二维码
关注或者微信搜一搜：编程智域 前端至全栈交流与成长
探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/
第一章：模型类元数据配置基础

1.1 模型定义与元数据

在FastAPI中使用Tortoise-ORM时，模型类通过Python类属性与数据库字段建立映射关系。每个模型类必须继承自tortoise.models.Model
，并通过class Meta定义元数据：
  1. from tortoise.models import Model
  2. from tortoise import fields
  5. class User(Model):
  6.     id = fields.IntField(pk=True)
  7.     username = fields.CharField(max_length=50, unique=True)
  8.     created_at = fields.DatetimeField(auto_now_add=True)
  10.     class Meta:
  11.         table = "auth_users"
  12.         table_description = "系统用户数据表"
  13.         schema = "public"
  14.         unique_together = (("username", "email"),)
复制代码
代码解析：

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

在FastAPI启动时初始化数据库连接，推荐使用lifespan事件处理：
  1. from contextlib import asynccontextmanager
  2. from fastapi import FastAPI
  3. from tortoise import Tortoise
  6. @asynccontextmanager
  7. async def lifespan(app: FastAPI):
  8.     await Tortoise.init(
  9.         db_url='postgres://user:pass@localhost:5432/mydb',
  10.         modules={'models': ['app.models']},
  11.         _create_db=True
  12.     )
  13.     await Tortoise.generate_schemas()
  14.     yield
  15.     await Tortoise.close_connections()
  18. app = FastAPI(lifespan=lifespan)
复制代码
关键参数说明：

  • modules：指定模型所在模块路径
  • _create_db：自动创建数据库（仅限开发环境）
  • generate_schemas：自动生成数据库表结构
第二章：aerich迁移工具实战

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/
2.1 aerich安装与初始化

安装命令：
  1. pip install aerich
复制代码
初始化迁移环境：
  1. aerich init -t app.config.TORTOISE_ORM
  2. aerich init-db
复制代码
在项目根目录创建aerich_config.py：
  1. TORTOISE_ORM = {
  2.     "connections": {"default": "postgres://user:pass@localhost:5432/mydb"},
  3.     "apps": {
  4.         "models": {
  5.             "models": ["app.models", "aerich.models"],
  6.             "default_connection": "default",
  7.         }
  8.     },
  9. }
复制代码
2.2 迁移操作流程


  • 创建迁移文件：
  1. aerich migrate --name add_user_table
复制代码

  • 查看未应用的迁移：
  1. aerich show migrations
复制代码

  • 执行升级：
  1. aerich upgrade
复制代码

  • 回滚变更：
  1. aerich downgrade -v -1
复制代码
2.3 迁移文件示例

生成的迁移文件migrations/20231111_1200_add_user_table.sql：
  1. -- upgrade --
  2. CREATE TABLE "auth_users"
  3. (
  4.     "id"         SERIAL      NOT NULL PRIMARY KEY,
  5.     "username"   VARCHAR(50) NOT NULL UNIQUE,
  6.     "created_at" TIMESTAMP   NOT NULL
  7. );
  8. COMMENT
  9. ON TABLE "auth_users" IS '系统用户数据表';
  10. -- downgrade --
  11. 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
往期文章归档：


  • 异步IO与Tortoise-ORM的数据库 | cmdragon's Blog
  • FastAPI数据库连接池配置与监控 | cmdragon's Blog
  • 分布式事务在点赞功能中的实现 | cmdragon's Blog
  • Tortoise-ORM级联查询与预加载性能优化 | cmdragon's Blog
  • 使用Tortoise-ORM和FastAPI构建评论系统 | cmdragon's Blog
  • 分层架构在博客评论功能中的应用与实现 | cmdragon's Blog
  • 深入解析事务基础与原子操作原理 | cmdragon's Blog
  • 掌握Tortoise-ORM高级异步查询技巧 | cmdragon's Blog
  • FastAPI与Tortoise-ORM实现关系型数据库关联 | cmdragon's Blog
  • Tortoise-ORM与FastAPI集成：异步模型定义与实践 | cmdragon's Blog
  • 异步编程与Tortoise-ORM框架 | cmdragon's Blog
  • FastAPI数据库集成与事务管理 | cmdragon's Blog
  • FastAPI与SQLAlchemy数据库集成 | cmdragon's Blog
  • FastAPI与SQLAlchemy数据库集成与CRUD操作 | cmdragon's Blog
  • FastAPI与SQLAlchemy同步数据库集成 | cmdragon's Blog
  • SQLAlchemy 核心概念与同步引擎配置详解 | cmdragon's Blog
  • FastAPI依赖注入性能优化策略 | cmdragon's Blog
  • FastAPI安全认证中的依赖组合 | cmdragon's Blog
  • FastAPI依赖注入系统及调试技巧 | cmdragon's Blog
  • FastAPI依赖覆盖与测试环境模拟 | cmdragon's Blog
  • FastAPI中的依赖注入与数据库事务管理 | cmdragon's Blog
  • FastAPI依赖注入实践：工厂模式与实例复用的优化策略 | cmdragon's Blog
  • FastAPI依赖注入：链式调用与多级参数传递 | cmdragon's Blog
  • FastAPI依赖注入：从基础概念到应用 | cmdragon's Blog
  • FastAPI中实现动态条件必填字段的实践 | cmdragon's Blog
  • FastAPI中Pydantic异步分布式唯一性校验 | cmdragon's Blog
  • 掌握FastAPI与Pydantic的跨字段验证技巧 | cmdragon's Blog
  • FastAPI中的Pydantic密码验证机制与实现 | cmdragon's Blog
  • 深入掌握FastAPI与OpenAPI规范的高级适配技巧 | cmdragon's Blog
  • Pydantic字段元数据指南：从基础到企业级文档增强 | cmdragon's Blog
  • Pydantic Schema生成指南：自定义JSON Schema | cmdragon's Blog
  • Pydantic递归模型深度校验36计：从无限嵌套到亿级数据的优化法则 | cmdragon's Blog
  • Pydantic异步校验器深：构建高并发验证系统 | cmdragon's Blog
  • Pydantic根校验器：构建跨字段验证系统 | cmdragon's Blog


来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

使用道具 举报
发帖
汲佩杉
2025-5-29 01:54:19

0

粉丝关注

14

主题发布

程序园子
微信扫一扫