目录一.ORM生态二.Tortoise-ORM配置三.Aerich 迁移工具的使用1.Aerich命令2.Aerich迁移四.Tortoise-ORM 的模型定义五.Tortoise-ORM CRUD增删改查六.Tortoise-ORM 的关联关系建立1.一对一2.一对多3.多对多七.Tortoise-ORM 的关联关系数据操作一.ORM生态ORM介绍ORMObject-Relational Mapping对象关系映射是一种编程技术用于在面向对象编程语言和关系型数据库之间建立映射。它允许开发者通过操作对象的方式来与数据库进行交互而无需直接编写复杂的 SQL语句。主要特点包括对象与数据库表的映射ORM将数据库中的表映射为编程语言中的类每一行数据对应一个对象表的列对应对象的属性。简化数据库操作开发者可以使用面向对象的方法如创建、查询、更新、删除对象来操作数据库而无需手动编写SQL。2跨数据库兼容ORM通常支持多种数据库如MySQL、PostgreSQL、SQLite通过统一的接口减少数据库切换的成本。3提高开发效率通过自动化SQL生成和查询优化减少重复代码提升开发速度。工作原理ORM框架定义了一个映射层将类和数据库表关联起来开发者通过ORM的API操作对象ORM自动将操作翻译成SQL语句执行数据库操作并返回结果优点提高代码可读性和维护性减少直接SQL操作带来的错误。支持复杂查询和关系如一对多、多对多缺点性能可能略低于原生SQL因抽象层开销对于非常复杂的查询可能需要直接编写SQLORM工具介绍SQLAlchemy同步/异步≈80%企业项目首选功能完备、社区成熟支持复杂查询和事务管理。Tortoise异步语法类似Django ORM适合异步优先项目集成简便GINO异步轻量级基于SQLAlchemy Core的异步扩展适合高性能API选型建议传统企业项目→SQLAlchemy成熟稳定全异步微服务→Tortoise-ORM或GINO二.Tortoise-ORM配置为什么选择Tortoise-ORM异步支持与FastAPI无缝集成简单易用的模型定义类似Django ORM支持复杂关系一对一、一对多、多对多自动生成表结构适合快速开发环境配置安装必要的依赖uv pip installtortoise-ormaerichaiomysqltomlkit# ORM基础配置 from tortoise.contrib.fastapi import register_tortoise from typing import Dict from fastapi import FastAPI app FastAPI() # Tortoise-ORM 配置 TORTOISE_ORM: Dict { # connections定义数据库连接字符串 connections: { # 开发环境使用 SQLite基于文件无需服务器 # default: sqlite://db.sqlite3, # 生产环境示例PostgreSQL # default: postgres://user:passwordlocalhost:5432/dbname, # 生产环境示例MySQL default: mysql://root:123456192.168.31.152:3306/fastapi_db, }, # 定义应用模块models 列表包含模型文件路径和Aerich的迁移模型 apps: { models: { models: [model19, aerich.models], # 模型模块和 Aerich 迁移模型 default_connection: default, #这里的default指的就是connections中的default } }, # 连接池配置推荐 use_tz: False, # 是否使用时区 timezone: UTC, # 默认时区 db_pool: { max_size: 10, # 最大连接数 min_size: 1, # 最小连接数 idle_timeout: 30 # 空闲连接超时秒 } } # 注册 Tortoise-ORM 到 FastAPI 应用 register_tortoise(app, configTORTOISE_ORM, generate_schemasTrue, # 开发环境自动生成表结构 add_exception_handlersTrue # 添加默认异常处理 ) if __name__ __main__: import uvicorn uvicorn.run(main19:app, host127.0.0.1, port8000, reloadTrue)三.Aerich 迁移工具的使用1.Aerich命令Aerich是Tortoise-ORM的数据库迁移工具用于管理数据库结构的变更。Aerich初始化在项目根目录运行以下命令aerich init-tmain.TORTOISE_ORM这将生成pyproject.tomlAerich配置文件指定迁移配置。migrations/迁移文件目录存放生成的.sql文件。aerich init-db生成和应用迁移1生成迁移文件 当模型发生变更时运行以下命令生成迁移文件aerich migrate--nameinfo2应用迁移 运行以下命令将迁移应用到数据库aerich upgrade3验证迁移 检查迁移历史aerich history4回滚迁移回退到指定版本aerich downgrade2.Aerich迁移先安装database client插件填写好信息点连接成功点加号在新连接这里点加号创建数据库点击Run新建数据库成功创建一个类文件model19.pyfrom tortoise.models import Model from tortoise.fields import CharField, DatetimeField, BooleanField class User(Model): id CharField(max_length36, pkTrue) # 主键UUID 字符串 username CharField(max_length50, uniqueTrue) # 用户名唯一 email CharField(max_length255, uniqueTrue) # 邮箱唯一 is_active BooleanField(defaultTrue) # 是否激活 email666 CharField(max_length255, uniqueTrue) # 邮箱唯一 class Meta: table users # 自定义表名 ordering [-created_at] # 默认按创建时间降序排序 def __str__(self): return self.username # 根据main19.py文件中的User模型去生成迁移文件,因为此文件里的TORTOISE_ORM变量相当于配置文件 # 这两个init初始化命令一般在项目周期里只执行一次 aerich init -t main19.TORTOISE_ORM # 初始化 aerich init-db # 创建迁移脚本一般是生成一堆类对应的迁移脚本 # 这两个迁移命令一般在项目周期一般执行很多次每次执行迁移(migrate)后都需要同步迁移upgrade到数据库 aerich migrate --name 注释 # 迁移 aerich upgrade # 同步迁移到数据库 配置和注册文件main19.py# ORM基础配置 from tortoise.contrib.fastapi import register_tortoise from typing import Dict from fastapi import FastAPI app FastAPI() # Tortoise-ORM 配置 TORTOISE_ORM: Dict { # connections定义数据库连接字符串 connections: { # 开发环境使用 SQLite基于文件无需服务器 # default: sqlite://db.sqlite3, # 生产环境示例PostgreSQL # default: postgres://user:passwordlocalhost:5432/dbname, # 生产环境示例MySQL default: mysql://root:root127.0.0.1:3306/fastapi_db, }, # 定义应用模块models 列表包含模型文件路径和Aerich的迁移模型 apps: { models: { # 根据model19.py文件中的User模型去生成迁移文件 models: [model19, aerich.models], # 模型模块和 Aerich 迁移模型 default_connection: default, #这里的default指的就是connections中的default } }, # 连接池配置推荐 use_tz: False, # 是否使用时区 timezone: UTC, # 默认时区 db_pool: { max_size: 10, # 最大连接数 min_size: 1, # 最小连接数 idle_timeout: 30 # 空闲连接超时秒 } } # 注册 Tortoise-ORM 到 FastAPI 应用 register_tortoise(app, configTORTOISE_ORM, generate_schemasTrue, # 开发环境自动生成表结构 add_exception_handlersTrue # 添加默认异常处理 ) if __name__ __main__: import uvicorn uvicorn.run(main19:app, host127.0.0.1, port8000, reloadTrue)依次执行那四个命令即可model19.py文件里注释写的非常明白。后续如果需要修改表结构直接修改代码即可比如把User类里的某个成员变量删了然后执行迁移和同步数据库就随之改变了确实好用啊太方便了。aerich migrate --name 注释 # 迁移 aerich upgrade # 同步迁移到数据库四.Tortoise-ORM 的模型定义Tortoise-ORM的模型通过继承tortoise.models.Model类定义每个模型对应数据库中的一张表。字段定义使用Tortoise-ORM提供的字段类型结合字段参数来指定约束和行为。继承Model所有模型必须继承tortoise.models.Model。字段定义每个字段对应数据库表中的一列使用Tortoise-ORM的字段类如CharField、BooleanField。Meta类用于定义模型的元数据如表名、排序规则等。核心字段类型详解Tortoise-ORM提供了多种字段类型用于定义数据库列的类型和行为。以下是常用的字段类型及其典型用途字段参数详解字段支持多种参数用于定义约束、默认值和其他行为。以下是常用参数max_length字符串字段的最大长度CharField必填null是否允许字段为空nullTrue表示数据库允许NULLdefault字段默认值如default0、defaultTrueunique是否唯一uniqueTrue确保字段值在表中唯一index是否创建索引indexTrue提高查询性能description字段描述用于文档或数据库注释pk是否为主键pkTrue表示该字段是主键validators自定义验证函数模型元数据Meta类Meta类用于定义模型的元数据控制表结构和查询行为。常用属性包括table自定义数据库表名如tableusersunique_together定义联合唯一约束如unique_together[(field1, field2)]indexes定义索引如indexes[(field1, field2)]ordering默认排序规则如ordering[-created_at, username]from tortoise.models import Model from tortoise.fields import CharField, TextField, IntField, BooleanField, DatetimeField class User(Model): id CharField(max_length36, pkTrue) name CharField(max_length64, uniqueTrue) email CharField(max_length255) is_active BooleanField(defaultTrue) age IntField(default0) # 创建时间 created_at DatetimeField(auto_now_addTrue) class Meta: table t_user # table/view unique_together (name, email) # 联合唯一 ordering [-created_at] # -降序 默认升序 # 创建索引 indexes [ email, ] aerich init -t main20.TORTOISE_ORM # 初始化 aerich init-db # 创建迁移脚本 aerich migrate --name 注释 # 迁移 aerich upgrade # 同步迁移 五.Tortoise-ORM CRUD增删改查model21.py 学生类from tortoise import fields, models class Student(models.Model): 学生模型包含基本信息。 用于演示单表的增删改查操作。 id fields.IntField(pkTrue, description学生ID主键) name fields.CharField(max_length50, description学生姓名) age fields.IntField(nullTrue, description学生年龄可为空) email fields.CharField(max_length100, uniqueTrue, nullTrue, description学生邮箱唯一) class Meta: table students def __str__(self): return fStudent: {self.name}, Age: {self.age}, Email: {self.email}main21.py 接口方式实现CRUD# ORM基础配置 from crud21 import create_student from tortoise.contrib.fastapi import register_tortoise from typing import Dict from fastapi import FastAPI app FastAPI() # Tortoise-ORM 配置 TORTOISE_ORM: Dict { connections: { # 开发环境使用 SQLite基于文件无需服务器 # default: sqlite://db.sqlite3, # 生产环境示例PostgreSQL # default: postgres://user:passwordlocalhost:5432/dbname, # 生产环境示例MySQL default: mysql://root:123456192.168.31.152:3306/fastapi_db3, }, apps: { models: { models: [model21, aerich.models], # 模型模块和 Aerich 迁移模型 default_connection: default, } }, # 连接池配置推荐 use_tz: False, # 是否使用时区 timezone: UTC, # 默认时区 db_pool: { max_size: 10, # 最大连接数 min_size: 1, # 最小连接数 idle_timeout: 30 # 空闲连接超时秒 } } register_tortoise(app, configTORTOISE_ORM, generate_schemasTrue, # 开发环境自动生成表结构 add_exception_handlersTrue # 添加默认异常处理 ) #创建对象时自动在数据库中插入了 app.get(/create) async def create(): stu await create_student(孙权, 18, sunquan163.com) return stu # 生成一个传递参数创建学生数据的路由 app.post(/create2) async def create2(name: str, age: int None, email: str None): stu await create_student(name, age, email) return stu if __name__ __main__: import uvicorn uvicorn.run(main21:app, host127.0.0.1, port8000, reloadTrue)crud21.py 脚本方式实现CRUDfrom model21 import Student from tortoise import Tortoise, run_async async def create_student(name: str, age: int None, email: str None) - Student: try: stu await Student.create(namename, ageage, emailemail) return stu except Exception as e: print(创建失败) async def update_student(stu_id: int, name: str None, age: int None, email: str None) - Student: stu await Student.get(idstu_id) # 判断用户传递了哪个数据如果没有传递就不更新 if name: stu.name name if age is not None: stu.age age if email is not None: stu.email email # 保存 await stu.save() return stu async def delete_student(stu_id: int) - None: stu await Student.get(idstu_id) await stu.delete() # 单条数据 async def get_student(stu_id: int) - Student: stu await Student.get(idstu_id) return stu # 多条数据 async def get_students(name: str) - list[Student]: 完成匹配 stus await Student.filter(namename) return stus async def get_students2(name: str) - list[Student]: 模糊查询 stus await Student.filter(name__containsname) return stus async def get_students3() - list[Student]: 获取所有数据 stus await Student.all() return stus # 编写查询名字为曹操的年龄等于20的记录 async def get_students4() - list[Student]: stus await Student.filter(name曹操, age20) return stus # 1. 直接测试脚本 # 2. 直接应用到接口 async def init(): await Tortoise.init( db_urlmysql://root:123456192.168.31.152:3306/fastapi_db3, modules{models: [model21]} ) await Tortoise.generate_schemas() async def main(): await init() # stu1 await create_student(name曹操) # print(f创建成功 ID:{stu1.id} Name:{stu1.name} Email:{stu1.email}) # stu2 await create_student(name刘备, age30) # print(f创建成功 ID:{stu2.id} Name:{stu2.name} Email:{stu2.email}) # stu3 await create_student(name张飞, age30, emailzf163.com) # print(f创建成功 ID:{stu3.id} Name:{stu3.name} Email:{stu3.email}) # stu4 await create_student(name关羽, age30, emailzf163.com) # print(f创建成功 ID:{stu4.id} Name:{stu4.name} Email:{stu4.email}) # await update_student(stu_id3, age36) # await update_student(stu_id1, emailccqq.com, age40) # await delete_student(stu_id9) stu await get_student(3) print(stu) stus1 await get_students(刘备) print(stus1) stus2 await get_students2(曹) print(stus2) stus3 await get_students3() print(stus3) if __name__ __main__: run_async(main())六.Tortoise-ORM 的关联关系建立我们将模拟一个学校管理系统包含以下实体学生Student每个学生有唯一的个人信息档案1对1。成绩Grade一个学生可以有多份成绩记录1对多。课程Course学生和课程之间是多对多关系通过成绩表关联。1.一对一# 关联关系建立1对1 from tortoise import fields, models, Tortoise, run_async class Student(models.Model): id fields.IntField(pkTrue) name fields.CharField(max_length50) # 参数on_deletefields.CASCADE 表示当学生被删除时其个人信息StudentProfile也会被删除 # 参数related_namestudent 表示在StudentProfile模型中有一个字段指向Student模型用于反向查询 profile fields.OneToOneField( models.StudentProfile, on_deletefields.CASCADE, related_namestudent) id name profile_id 1 张三 1 2 李四 2 id address phone 1 上海 123456 2 北京 789456 class StudentProfile(models.Model): id fields.IntField(pkTrue) address fields.CharField(max_length100) phone fields.CharField(max_length20) async def init(): await Tortoise.init( db_urlmysql://root:123456192.168.31.152:3306/fastapi_db4, modules{models: [model22]} ) await Tortoise.generate_schemas() if __name__ __main__: run_async(init())2.一对多# 关联关系建立1对多 from tortoise import fields, models, Tortoise, run_async class Student(models.Model): id fields.IntField(pkTrue) name fields.CharField(max_length50) profile fields.OneToOneField( models.StudentProfile, on_deletefields.CASCADE, related_namestudent) 学生表 id name profile_id score_ids score_id1 score_id2 ... 1 张三 1 1-2-3-5-8-6-7 1 2 2 李四 2 成绩表 id score stu_id 1 90 1 2 80 1 3 70 1 4 60 2 5 50 1 class StudentProfile(models.Model): id fields.IntField(pkTrue) address fields.CharField(max_length100) phone fields.CharField(max_length20) #一对多在多的一方定义外键 class Grade(models.Model): id fields.IntField(pkTrue) score fields.FloatField() student fields.ForeignKeyField( models.Student, related_namegrades, on_deletefields.CASCADE) async def init(): await Tortoise.init( db_urlmysql://root:123456192.168.31.152:3306/fastapi_db4, modules{models: [model23]} ) await Tortoise.generate_schemas() if __name__ __main__: run_async(init())3.多对多model24.py# 关联关系建立多对多 from tortoise import fields, models, Tortoise, run_async 学生表 id name profile_id 1 张三 1 2 李四 2 成绩表 id score stu_id 1 90 1 2 80 1 3 70 1 4 60 2 5 50 1 课程表 id name 1 python 2 java 3 c 学生课程表 stu_id course_id 1 1 1 2 2 3 class Student(models.Model): id fields.IntField(pkTrue) name fields.CharField(max_length50) profile fields.OneToOneField( models.StudentProfile, on_deletefields.CASCADE, related_namestudent, nullTrue) class StudentProfile(models.Model): id fields.IntField(pkTrue) address fields.CharField(max_length100) phone fields.CharField(max_length20) class Grade(models.Model): id fields.IntField(pkTrue) score fields.FloatField() student fields.ForeignKeyField( models.Student, related_namegrades, on_deletefields.CASCADE) class Course(models.Model): id fields.IntField(pkTrue) name fields.CharField(max_length50) # students fields.ManyToManyField( # models.Student, related_namecourses, throughstudentcourse) class StudentCourse(models.Model): students fields.ForeignKeyField(models.Student, related_namecourses) courses fields.ForeignKeyField(models.Course, related_namestudents) class Meta: unique_together (students, courses) async def init(): await Tortoise.init( db_urlmysql://root:root127.0.0.1:3306/fastapi_db4, modules{models: [model24]} ) await Tortoise.generate_schemas() if __name__ __main__: run_async(init())七.Tortoise-ORM 的关联关系数据操作基于关联关系CRUD# 关联关系的增删改查询 from tortoise import Tortoise, run_async from model24 import Student, Course, StudentCourse, Grade, StudentProfile async def init(): await Tortoise.init( db_urlmysql://root:123456192.168.31.152:3306/fastapi_db4, modules{models: [model24]} ) async def create_data(): await init() # 1对1 # 学生对象的id会自动生成profile对象是关联用的所以不用必须赋初值 # 下面两句create语句会落实到数据库 # stu1 await Student.create(name董卓) # pro1 await StudentProfile.create(address上海, phone123456) # 这句代码只是在内存里赋值并不会落实到数据库所以需要save操作 # stu1.profile pro1 # 保存学生对象会自动保存关联的profile对象并落实到数据库 # await stu1.save() # pro2 await StudentProfile.create(address北京, phone123456) # stu2 await Student.create(name刘备, profilepro2) # 1对多 stu3 await Student.create(name孙权) await Grade.create(score100, studentstu3) await Grade.create(score90, studentstu3) await Grade.create(score80, studentstu3) # 多对多 stu4 await Student.create(name关羽) stu5 await Student.create(name张飞) cou1 await Course.create(namePython) cou2 await Course.create(nameC) await StudentCourse.create(studentsstu4, coursescou1) await StudentCourse.create(studentsstu4, coursescou2) await StudentCourse.create(studentsstu5, coursescou1) await StudentCourse.create(studentsstu5, coursescou2) async def update_data(): await init() # 1对1 # 先从数据库取出 stu await Student.get(id1) pro await StudentProfile.create(address上海, phone12345678901) stu.profile pro # 存回数据库 await stu.save() # 1对多 # 方式一 stu2 await Student.get(id1) grade1 await Grade.get(id1) grade1.student stu2 await grade1.save() # 方式二 await Grade.filter(id6).update(studentstu2) async def query_data(): await init() stu await Student.get(id1) print(stu.name) # 关联对象profile需要异步获取 方式一 pro await stu.profile print(pro.address) print(pro.phone) # 关联对象profile需要异步获取 方式二 stu2 await Student.get(id1).prefetch_related(profile) # 获取关联数据 print(stu2.profile.address) print(stu2.profile.phone) #all()加不加都行一般不影响查询结果 stu3 await Student.get(id9).prefetch_related(grades).all() for grade in stu3.grades: print(grade.score) async def delete_data(): await init() # grade await Grade.get(id9) # await grade.delete() #级联删除 stu await Student.get(id9) await stu.delete() if __name__ __main__: # run_async(create_data()) # run_async(update_data()) # run_async(query_data()) run_async(delete_data())