Tortoise ORM 和 Aerich 使用文档参考表

前言

Tortoise ORM 和 Aerich 是 Python 异步 ORM 框架，本文将对两者的使用文档进行参考，帮助读者更好地理解两者的用法。
制作不易，禁止商业用途，转载请标明出处，具体情况或反馈请联系作者。
如果觉得对您有帮助，欢迎在文章底部请博主喝杯奶茶，您的鼓励就是俺最大的动力！😄

安装

操作命令说明
安装 Tortoise ORMpip install tortoise-orm安装 Tortoise ORM 库
安装 Aerichpip install aerich安装 Aerich 迁移工具
一条龙服务pip install fastapi uvicorn tortoise-orm tortoise-orm[asyncmy] tortoise-orm[accel]安装 Tortoise ORM 库、Aerich 迁移工具、FastAPI、Uvicorn、asyncmy、accel 等依赖库及加速器

TORTOISE_ORM配置

from tortoise import Tortoise

# 配置 MySQL 数据库
TORTOISE_ORM = {
    "connections": {
        "default": {
            # "engine": "tortoise.backends.asyncpg",   # 数据库引擎 PostgresQL
            "engine": "tortoise.backends.mysql",  # 数据库引擎 Mysql or Mariadb
            "credentials": {
                "host": "127.0.0.1",    # 地址
                "port": "3306",         # 端口
                "user": "root",         # 用户名
                "password": "root",     # 密码
                "database": "fastapi",  # 数据库名称（需要提前创建数据库）
                "minsize": 1,           # 最少连接
                "maxsize": 5,           # 最大连接
                "charset": "utf8mb4",   # 编码
                "echo": True            # 是否反馈SQL语句
            }
        }
    },
    "apps": {
        "models": {
            "models": ["models", "aerich.models"],   # models数据模型迁移
            "default_connection": "default"
        }
    },
    "use_tz": False,
    "timezone": "Asia/Shanghai"
}

# 初始化 Tortoise ORM
Tortoise.init(config=TORTOISE_ORM)

# 创建表
Tortoise.generate_schemas()

Tortoise ORM 字段类型参数整理

通用字段参数

这些参数适用于所有字段类型。

参数名类型描述
defaultAny字段的默认值。
nullbool是否允许字段为NULL。
uniquebool字段值是否必须在数据库中唯一。默认为False。
indexbool是否为该字段创建索引。默认为False。
descriptionstr字段的描述信息，主要用于文档和生成的SQL schema。
pkbool是否将此字段设置为主键。默认为False。
generatedbool是否为自动生成的字段（如自增主键）。默认为False。

字段类型特定参数

CharField（字符串类型字段）

额外参数名类型描述
max_lengthint字符串的最大长度。

FloatField（浮点类型字段）

额外参数名类型描述
gtint字段值大于指定值的范围限制。
ltint字段值小于指定值的范围限制。
geint字段值大于等于指定值的范围限制。
leint字段值小于等于指定值的范围限制。

IntegerField（整数类型字段）

额外参数名类型描述
gtint字段值大于指定值的范围限制。
ltint字段值小于指定值的范围限制。
geint字段值大于等于指定值的范围限制。
leint字段值小于等于指定值的范围限制。

BooleanField（布尔类型字段）

额外参数名类型描述
defaultAny字段的默认值。

DateField & DateTimeField（日期时间类型字段）

额外参数名类型描述
auto_nowbool如果设置为True，则在对象每次保存时自动设置为当前日期/时间。
auto_now_addbool如果设置为True，则在对象第一次保存时自动设置为当前日期/时间。

ForeignKeyField（关系型字段）

额外参数名类型描述
tostr or Type[Model]指定外键关联的模型。
related_namestr在关联模型上创建反向关系的名称。
on_deletestr当关联的对象被删除时的行为（如CASCADE、SET_NULL等）。

ManyToManyField（多对多关系型字段）

额外参数名类型描述
through-用于定义多对多关系的中间表。如果不指定，Tortoise ORM将自动创建一个中间表。
related_namestr用于反向查询。

TextField（文本类型字段）

额外参数名类型描述
defaultAny字段的默认值。

JSONField（序列化类型字段）

额外参数名类型描述
defaultAny字段的默认值。

初始化配置

操作命令说明
初始化 Aerich 配置aerich init -t your_settings_path_.TORTOISE_ORM只需使用一次，初始化配置文件

数据库初始化

操作命令说明
初始化数据库aerich init-db一般情况下只需在第一次使用，初始化数据库表结构

数据迁移操作

操作命令说明
数据迁移aerich migrate [--name]执行数据迁移操作
aerich migrate --name add_column示例：标记本次迁移操作为 add_column

模型版本管理

操作命令说明
升级模型版本aerich upgrade更新数据模型版本
降级模型版本aerich downgrade回退数据模型版本
查看迁移历史aerich history查看历史迁移记录

Tortoise ORM 查询参数详细说明

方法描述示例查询
get()根据主键获取单条数据。如果数据不存在，将返回 None。Model.get(id=1)
all()查询所有数据，返回所有数据集（QuerySet 对象）。如果不加任何条件，它会返回表中的所有记录。Model.all()
filter()根据条件查询数据，返回满足条件的数据集（QuerySet 对象）。可以使用 all() 方法获取所有的查询结果，或者使用 first() 方法获取第一个结果。Model.filter(name='John')
exclude()排除满足条件的数据，返回不满足条件的数据集。Model.exclude(name='John')
count()统计满足条件的数据数量。Model.filter(name='John').count()
order_by()按照指定字段排序查询结果。Model.all().order_by('name')

查询条件

运算符描述示例查询
__range查询在指定范围之间。Model.filter(age__range=(20, 30))
__isnull是否为空（IS NULL）。Model.filter(field__isnull=True)
__regex正则表达式匹配（REGEXP 或 LIKE，取决于数据库）。Model.filter(name__regex=r'John.*')
__iregex不区分大小写的正则表达式匹配（IREGEXP 或 ILIKE，取决于数据库）。Model.filter(name__iregex=r'john.*')
=精确匹配。Model.filter(name='John')
__not不等于。Model.filter(name__not='John')
__gt大于。Model.filter(age__gt=30)
__gte大于或等于。Model.filter(age__gte=30)
__lt小于。Model.filter(age__lt=30)
__lte小于或等于。Model.filter(age__lte=30)
__in成员运算符，用于查询在指定列表中的值。Model.filter(id__in=[1, 2, 3])
__nin成员运算符，用于查询不在指定列表中的值。Model.filter(id__nin=[1, 2, 3])
__icontains模糊查询，包含指定字符串，不区分大小写。Model.filter(name__icontains='john')
__istartswith模糊查询，字符串以指定值开头，不区分大小写。Model.filter(name__istartswith='john')
__iendswith模糊查询，字符串以指定值结尾，不区分大小写。Model.filter(name__iendswith='john')

Trotoise ORM 修改数据

一对多查询、多对多查询

一对多查询

查询所有学生的姓名

方法描述
await Student.all().values("name")获取所有学生的姓名

查询特定学生信息

方法描述
await Student.get(name="张三")获取姓名为"张三"的学生对象
属性描述
students.sno学号，2001
students.name姓名，张三
students.clazzs_id班级编号（外键），1
await students.clazzs.values("name")查询班级名称，{'name': '计算机科学与技术'}

多对多查询

查询学生课程信息

方法描述
await Student.all().values("name", "clazzs__name")获取所有学生的姓名和班级名称
await Student.get(name="张三")获取姓名为"张三"的学生对象
await students.courses.all()张三学生所有的课程（一对多）
await students.courses.all().values("name")张三学生所有的课程的名称（一对多）
await students.courses.all().values("name", "teacher__name")张三学生所有的课程的名称和教师名称
await Student.all().values("name", "clazzs__name", "courses__name")多个学生的所有课程对应的所有教师（多对多）

分页查询

方法描述
await Student.all().limit(5)获取前5个学生
await Student.all().offset(5).limit(5)跳过前5个学生，再获取5个学生
await Student.filter(age__gt=20).limit(10)获取年龄大于20的前10个学生
await Student.filter(age__gt=20).filter(name__contains="Hans")获取年龄大于20且姓名包含"Hans"的学生

Tortoise ORM 数据修改

方法描述
Student.filter(id=1).update(name="张三")根据学生ID修改学生姓名为"张三"
students = await Student.all()获取所有学生
for student in students: student.name += "Aa"批量更新学生姓名，在每个姓名后面添加字符"Aa"

Trotoise ORM 新增数据

方法描述
await Student.create(name="张不四", pwd=123456, sno=2007, clazzs_id=2)新增一条学生数据
await Student.bulk_create([Student(name="批量新增名称"+str(i), pwd=123456, sno=2007+i, clazzs_id=2) for i in range(3)])批量新增多条学生数据
方法描述
await Student.create(...)新增一条学生数据
await Student.bulk_create([...])bulk_create() 方法是 Tortoise ORM 中用于批量新增数据的函数。该方法可以一次性将多个数据对象批量插入到数据库中，从而提高数据插入的效率。

示例：批量新增学生数据

create_student_object_list = await Student.bulk_create([
    Student(name="批量新增名称"+str(i), pwd=123456, sno=2007+i, clazzs_id=2) for i in range(3)
])

在这段代码中，我们首先创建了一个包含多个学生对象的列表，每个学生对象具有不同的属性。然后我们调用 bulk_create() 方法，传递包含学生对象的列表作为参数。Tortoise ORM 会将列表中的每个学生对象批量插入到数据库中。

通过使用 bulk_create() 方法，可以减少与数据库的交互次数，提高数据插入的效率，特别是在需要批量插入大量数据时尤为有用。