Tortoise ORM 和 Aerich 使用文档参考表

前言

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

安装

操作	命令	说明
安装 Tortoise ORM	`pip install tortoise-orm`	安装 Tortoise ORM 库
安装 Aerich	`pip 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 字段类型参数整理

通用字段参数

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

参数名	类型	描述
default	Any	字段的默认值。
null	bool	是否允许字段为NULL。
unique	bool	字段值是否必须在数据库中唯一。默认为False。
index	bool	是否为该字段创建索引。默认为False。
description	str	字段的描述信息，主要用于文档和生成的SQL schema。
pk	bool	是否将此字段设置为主键。默认为False。
generated	bool	是否为自动生成的字段（如自增主键）。默认为False。

字段类型特定参数

CharField（字符串类型字段）

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

FloatField（浮点类型字段）

额外参数名	类型	描述
gt	int	字段值大于指定值的范围限制。
lt	int	字段值小于指定值的范围限制。
ge	int	字段值大于等于指定值的范围限制。
le	int	字段值小于等于指定值的范围限制。

IntegerField（整数类型字段）

额外参数名	类型	描述
gt	int	字段值大于指定值的范围限制。
lt	int	字段值小于指定值的范围限制。
ge	int	字段值大于等于指定值的范围限制。
le	int	字段值小于等于指定值的范围限制。

BooleanField（布尔类型字段）

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

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

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

ForeignKeyField（关系型字段）

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

ManyToManyField（多对多关系型字段）

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

TextField（文本类型字段）

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

JSONField（序列化类型字段）

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

初始化配置

操作	命令	说明
初始化 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() 方法，可以减少与数据库的交互次数，提高数据插入的效率，特别是在需要批量插入大量数据时尤为有用。