Tortoise-ORM 集成：数据库连接与框架搭建实战指南

1. 引言为什么选择 Tortoise-ORMTortoise-ORM 是一个基于 Python asyncio 的异步对象关系映射ORM框架专为 FastAPI、Django 等异步 Web 框架设计。它借鉴了 Django ORM 的易用性同时提供了原生的异步支持使得在高并发场景下处理数据库操作更加高效。本文将详细介绍如何将 Tortoise-ORM 集成到你的项目中完成从数据库连接到完整框架搭建的全过程。2. 环境准备与安装在开始集成之前请确保你的 Python 环境已就绪。2.1 安装 Tortoise-ORM使用 pip 安装 Tortoise-ORM 核心库pip install tortoise-orm安装 MySQL 异步驱动pip install asyncmy安装 Aerich 迁移工具pip install aerich安装 FastAPI 和 Uvicorn 已安装跳过pip install fastapi uvicorn[standard]2.2 项目结构建议一个清晰的项目结构有助于后续维护。建议采用以下目录组织3. 数据库连接配置Tortoise-ORM 支持多种数据库配置方式统一且灵活。在此之前确认启动 MySQL 服务有mysql可在命令行中启动mysql -u root -p输入密码 启动成功后进行下一步操作。3.1 基础连接配置新建Faster API项目 上一个博客在config.py中定义数据库连接配置python # app/config.py 数据库配置文件 这个文件定义了 Tortoise-ORM 连接 MySQL 数据库所需的所有配置信息 # TORTOISE_ORM 是 Tortoise-ORM 规定的配置字典变量名 # 后面用 register_tortoise 或 Aerich 时都会引用这个字典 TORTOISE_ORM { # 1. 连接配置 —— 定义数据库连接信息 connections: { # default 是默认连接的名字必须有一个 default default: { # engine指定数据库后端引擎MySQL 使用 tortoise.backends.mysql engine: tortoise.backends.mysql, # credentials数据库连接凭证包含主机、端口、用户名、密码等 credentials: { host: 127.0.0.1, # MySQL 服务器地址 port: 3306, # MySQL 端口默认 3306 user: root, # 数据库用户名 password: 123456, # 数据库密码请根据实际情况修改 database: fastapi_db1, # 数据库名称 minsize: 1, # 连接池最小连接数 maxsize: 5, # 连接池最大连接数 charset: utf8mb4, # 字符集支持 emoji echo: True # 是否打印 SQL 语句开发环境建议开启 } } }, # 2. 应用配置 —— 指定模型所在的模块 apps: { # models 是应用的名字可以自定义但 Aerich 需要使用这个名字 models: { # models 列表指定包含 Tortoise 模型类的 Python 模块路径 # aerich.models 是 Aerich 的内置模型用于记录迁移历史必须包含 models: [app.models, aerich.models], # default_connection指定这个应用使用哪个数据库连接 default_connection: default, } }, # 3. 时区配置 use_tz: False, # 是否使用时区 timezone: Asia/Shanghai # 时区设置 } 3.2 初始化数据库连接在应用启动时main.py中初始化 Tortoise-ORMfrom fastapi import FastAPI from tortoise.contrib.fastapi import register_tortoise from app.config import TORTOISE_ORM app FastAPI() register_tortoise( app, configTORTOISE_ORM, generate_schemasTrue, add_exception_handlersTrue ) app.get(/) async def root(): return {message: Hello World} app.get(/hello/{name}) async def say_hello(name: str): return {message: fHello {name}}4. 定义数据模型Tortoise-ORM 的模型定义方式与 Django ORM 非常相似。4.1 基础模型示例项目中新建python软件包 app在 app/models/user.py中定义一个用户模型from tortoise import models, fields class User(models.Model): id fields.IntField(pkTrue) username fields.CharField(max_length255, uniqueTrue) email fields.CharField(max_length255, uniqueTrue) phone fields.CharField(max_length20, uniqueTrue,nullTrue) is_active fields.BooleanField(defaultTrue) created_at fields.DatetimeField(auto_now_addTrue) updated_at fields.DatetimeField(auto_nowTrue) class Meta: table t_user table_description 用户表 ordering [id] def __str__(self): return self.username导出user模型app/models/init.pyfrom app.models.user import User __all__ [User]4.2 Aerich 数据库迁移在项目根目录执行以下命令aerich init -t app.config.TORTOISE_ORMaerich init执行 aerich 初始化操作会在项目根目录生成pyproject.toml配置文件、创建migrations迁移文件夹-t全称--tortoise-orm用来指定 TortoiseORM 配置对象的导入路径app.config.TORTOISE_ORM代表从app包下的config.py文件读取TORTOISE_ORM数据库配置字典。初始迁移并应用到数据库aerich init-db4.3 查询数据app/routers/user.py先在数据库任意添加几条数据也可执行sql语句实现INSERT INTO t_user (username,email,phone,is_active,created_at,updated_at) VALUES (user01,user01example.com,13000000001,1,2026-01-01 10:00:00,2026-01-01 10:00:00), (user02,user02example.com,13000000002,1,2026-01-01 10:01:00,2026-01-01 10:01:00), (user03,user03example.com,13000000003,0,2026-01-01 10:02:00,2026-01-01 10:02:00), (user04,user04example.com,13000000004,1,2026-01-01 10:03:00,2026-01-01 10:03:00), (user05,user05example.com,NULL,1,2026-01-01 10:04:00,2026-01-01 10:04:00), (user06,user06example.com,13000000006,0,2026-01-01 10:05:00,2026-01-01 10:05:00), (user07,user07example.com,13000000007,1,2026-01-01 10:06:00,2026-01-01 10:06:00), (user08,user08example.com,13000000008,1,2026-01-01 10:07:00,2026-01-01 10:07:00), (user09,user09example.com,NULL,0,2026-01-01 10:08:00,2026-01-01 10:08:00), (user10,user10example.com,13000000010,1,2026-01-01 10:09:00,2026-01-01 10:09:00), (user11,user11example.com,13000000011,1,2026-01-01 10:10:00,2026-01-01 10:10:00), (user12,user12example.com,13000000012,0,2026-01-01 10:11:00,2026-01-01 10:11:00), (user13,user13example.com,13000000013,1,2026-01-01 10:12:00,2026-01-01 10:12:00), (user14,user14example.com,NULL,1,2026-01-01 10:13:00,2026-01-01 10:13:00), (user15,user15example.com,13000000015,0,2026-01-01 10:14:00,2026-01-01 10:14:00), (user16,user16example.com,13000000016,1,2026-01-01 10:15:00,2026-01-01 10:15:00), (user17,user17example.com,13000000017,1,2026-01-01 10:16:00,2026-01-01 10:16:00), (user18,user18example.com,13000000018,0,2026-01-01 10:17:00,2026-01-01 10:17:00), (user19,user19example.com,NULL,1,2026-01-01 10:18:00,2026-01-01 10:18:00), (user20,user20example.com,13000000020,1,2026-01-01 10:19:00,2026-01-01 10:19:00), (user21,user21example.com,13000000021,0,2026-01-01 10:20:00,2026-01-01 10:20:00), (user22,user22example.com,13000000022,1,2026-01-01 10:21:00,2026-01-01 10:21:00), (user23,user23example.com,13000000023,1,2026-01-01 10:22:00,2026-01-01 10:22:00), (user24,user24example.com,NULL,0,2026-01-01 10:23:00,2026-01-01 10:23:00), (user25,user25example.com,13000000025,1,2026-01-01 10:24:00,2026-01-01 10:24:00), (user26,user26example.com,13000000026,1,2026-01-01 10:25:00,2026-01-01 10:25:00), (user27,user27example.com,13000000027,0,2026-01-01 10:26:00,2026-01-01 10:26:00), (user28,user28example.com,13000000028,1,2026-01-01 10:27:00,2026-01-01 10:27:00), (user29,user29example.com,NULL,1,2026-01-01 10:28:00,2026-01-01 10:28:00), (user30,user30example.com,13000000030,0,2026-01-01 10:29:00,2026-01-01 10:29:00);新建routers 软件包 当前目录下创建user.pyfrom fastapi import APIRouter from app.models import User from schemas.user import UserCreateRequest, UserUpdateRequest, UserLoginRequest user_router APIRouter( prefix/users, tags[用户管理] ) user_router.get(all/,summary获取所有用户,description获取所有用户) async def getSllUser(): users1 await User.all() user1 await User.get(id 1) user2 await User.get_or_none(id 100) return { code:1, message:success, data:{ users1:users1, user1:user1, user2:user2 } }在main.py中注册子路由from fastapi import FastAPI from tortoise.contrib.fastapi import register_tortoise from app.config import TORTOISE_ORM from app.routers.user import user_router # 定义 lifespan 生命周期函数 app FastAPI() app.include_router(user_router) register_tortoise( appapp, configTORTOISE_ORM, generate_schemasTrue, add_exception_handlersTrue )运行项目High Performance Web Crawler API - Swagger UI