Tortoise-ORM 入门指南：Python异步ORM框架快速上手

Tortoise-ORM 入门指南：Python异步ORM框架快速上手

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm

前言

Tortoise-ORM 是一个基于 Python asyncio 的异步对象关系映射(ORM)框架，专为现代异步Python应用设计。它借鉴了Django ORM的设计理念，同时充分利用了Python的异步特性，为开发者提供了简洁高效的数据库操作体验。

安装指南

基础安装

Tortoise-ORM 支持多种数据库后端，安装时需要根据使用的数据库类型选择对应的依赖：

# SQLite (默认包含)
pip install tortoise-orm

# PostgreSQL (选择psycopg或asyncpg驱动)
pip install "tortoise-orm[psycopg]"
# 或
pip install "tortoise-orm[asyncpg]"

# MySQL (选择aiomysql或asyncmy驱动)
pip install "tortoise-orm[aiomysql]"
# 或
pip install "tortoise-orm[asyncmy]"

# MS SQL 或 Oracle
pip install "tortoise-orm[asyncodbc]"

性能优化依赖

为了获得更好的性能，可以安装以下可选依赖：

# 安装所有性能优化依赖
pip install "tortoise-orm[accel]"

各优化包的作用：

• orjson: 提供更快的JSON序列化/反序列化
• uvloop: 替代标准asyncio事件循环，提升性能
• ciso8601: 优化日期时间处理(Windows需手动安装)

模型定义

Tortoise-ORM 的模型定义非常直观，继承自 tortoise.models.Model 类即可：

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)

class Event(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)
    # 外键关系定义
    tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
    # 多对多关系
    participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')

class Team(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)

模型定义要点：

1. id 字段可省略，系统会自动创建
2. 外键关系使用 ForeignKeyField 定义
3. 多对多关系使用 ManyToManyField 定义，可指定中间表
4. related_name 用于反向查询

初始化与连接

使用前需要初始化Tortoise ORM并建立数据库连接：

from tortoise import Tortoise, run_async

async def init():
    await Tortoise.init(
        db_url='sqlite://db.sqlite3',  # 数据库URL
        modules={'models': ['app.models']}  # 模型所在模块
    )
    await Tortoise.generate_schemas()  # 生成数据库表结构

run_async(init())

初始化参数说明：

• db_url: 数据库连接字符串，格式为 dialect://user:password@host:port/database
• modules: 指定模型所在的Python模块路径

基础CRUD操作

创建记录

# 方式1: 先创建实例再保存
tournament = Tournament(name='New Tournament')
await tournament.save()

# 方式2: 直接使用create方法
await Event.create(name='Without participants', tournament=tournament)

查询记录

# 获取所有记录
teams = await Team.all()

# 条件过滤
events = await Event.filter(name__startswith='Test')

# 关联查询
tournaments = await Tournament.filter(events__name='Test')

更新记录

event = await Event.get(id=1)
event.name = 'Updated Event'
await event.save()

删除记录

await Event.filter(id=1).delete()

关联关系操作

一对多关系

# 获取赛事的所有活动
tournament = await Tournament.get(id=1)
events = await tournament.events.all()

多对多关系

event = await Event.get(id=1)
team = await Team.get(id=1)

# 添加关联
await event.participants.add(team)

# 移除关联
await event.participants.remove(team)

# 清空关联
await event.participants.clear()

预取关联数据

# 预取单层关联
events = await Event.all().prefetch_related('tournament')

# 预取多层关联
teams = await Team.all().prefetch_related('events__tournament')

高级查询

排序与去重

# 按名称降序
await Tournament.all().order_by('-name')

# 关联模型排序并去重
await Tournament.filter(
    events__name__in=['Test', 'Prod']
).order_by('-events__participants__name').distinct()

聚合查询

from tortoise.functions import Count

# 统计每个赛事的活动数量
await Tournament.annotate(events_count=Count('events')).values('name', 'events_count')

最佳实践

1. 生产环境：不要使用generate_schemas()，应使用迁移工具管理数据库变更
2. 性能优化：合理使用prefetch_related避免N+1查询问题
3. 事务管理：关键操作应放在事务中执行
4. 连接池：生产环境应配置适当的连接池大小

总结

Tortoise-ORM 为Python异步应用提供了强大而简洁的ORM解决方案。通过本指南，您已经掌握了模型定义、数据库连接、基本CRUD操作和关联关系处理等核心功能。随着对框架的深入使用，您会发现它在处理复杂数据关系和高并发场景下的出色表现。

对于更高级的功能如事务管理、多数据库支持和复杂查询，建议参考官方文档中的进阶示例和API参考。

tortoise-orm tortoise/tortoise-orm: 是一个基于 Python 的对象关系映射 (ORM) 库，它支持 SQLite、 MySQL、 PostgreSQL 等多种数据库。适合用于 Python 应用程序的数据库操作和 ORM，特别是对于需要轻量级、高性能的 ORM 库的场景。特点是轻量级、高性能、支持多种数据库、易于使用。 项目地址: https://gitcode.com/gh_mirrors/to/tortoise-orm