数据库后端【免费下载链接】tortoise-ormFamiliar asyncio ORM for python, built with relations in mind项目地址https://gitcode.com/gh_mirrors/to/tortoise-orm点击查看免费下载本文以 Tortoise-ORM 仓库中 Sanic 集成示例 为主线系统讲解如何通过tortoise.contrib.sanic.register_tortoise在 Sanic 应用中完成 ORM 的启动初始化、建表与关闭清理。读者读完本文将掌握示例应用的真实代码结构、register_tortoise全部参数的用法与底层实现、Sanic 多进程下的生命周期钩子原理以及如何用 sanic-testing 编写集成测试。一句话理解 register_tortoiseTortoise-ORM 为 Sanic 提供了一个轻量级集成工具tortoise.contrib.sanic它只暴露一个函数register_tortoise在服务启动时startup设置好 Tortoise-ORM在服务关闭时teardown自动清理连接。这是 Tortoise-ORM 官方contrib集成体系中与 aiohttp、Starlette、FastAPI、BlackSheep 等方案并列的 Sanic 专用入口官方使用说明见 docs/contrib/sanic.rst。示例项目结构仓库中的 examples/sanic 目录是一个最小但完整可运行的 Sanic 集成示例包含四个文件文件作用examples/sanic/models.py定义 Tortoise-ORM 数据模型examples/sanic/main.pySanic 应用入口调用register_tortoiseexamples/sanic/_tests.py基于 sanic-testing 的集成测试examples/sanic/README.rst示例说明文档启动方式与原文档一致只需在示例目录下执行python3 main.py依赖方面Sanic 与 sanic-testing 已被列入项目contrib可选依赖组见 pyproject.toml安装时使用pip install tortoise-orm[contrib]即可一并获得。数据模型先定义 Usersmodels.py 定义了本示例唯一的模型from tortoise import Model, fields class Users(Model): id fields.IntField(primary_keyTrue) name fields.CharField(50) def __str__(self): return fUser {self.id}: {self.name}这里展示了 Tortoise-ORM 建模的两种最基础字段fields.IntField(primary_keyTrue)整数型主键fields.CharField(50)最大长度 50 的字符串字段与 Django ORM 的字段风格一致。__str__方法让模型实例在str(user)时输出User 1: New User这类可读文本后面的路由与测试都依赖这一输出格式。应用入口路由 register_tortoisemain.py 是集成示例的核心import logging from models import Users from sanic import Sanic, response from tortoise.contrib.sanic import register_tortoise logging.basicConfig(levellogging.DEBUG) app Sanic(__name__) app.route(/) async def list_all(request): users await Users.all() return response.json({users: [str(user) for user in users]}) app.post(/user) async def add_user(request): user await Users.create(nameNew User) return response.json({user: str(user)}) register_tortoise( app, db_urlsqlite://db.sqlite3, modules{models: [models]}, generate_schemasTrue ) if __name__ __main__: app.run(port5000, debugTrue)示例包含两个路由GET /查询全部用户并以 JSON 返回POST /user创建一个名为New User的用户。注意查询/创建操作直接使用异步 ORM APIawait Users.all()、await Users.create(...)因为 Sanic 的事件循环与 Tortoise-ORM 的异步驱动天然兼容。关键一行是应用底部对register_tortoise的调用它使用最简配置组合(db_url, modules)完成初始化db_urlsqlite://db.sqlite3以 DB_URL 字符串形式指向 SQLite 数据库文件modules{models: [models]}声明应用名models及其需要扫描的模型模块models即本目录下的 models.pygenerate_schemasTrue服务启动时自动按模型建表。register_tortoise 参数完全解读register_tortoise的完整签名位于 tortoise/contrib/sanic/init.pydef register_tortoise( app: Sanic, config: dict | None None, config_file: str | None None, db_url: str | None None, modules: dict[str, Iterable[str | ModuleType]] | None None, generate_schemas: bool False, _enable_global_fallback: bool True, ) - None:三种互斥的配置方式参数说明明确要求只能使用config、config_file与(db_url, modules)三组中的一组它们最终都会透传给 Tortoise.init。方式一config字典配置直接传入完整配置字典支持多连接、多应用与路由配置register_tortoise( app, config{ connections: { # Dict 格式的连接 default: { engine: tortoise.backends.asyncpg, credentials: { host: localhost, port: 5432, user: tortoise, password: qwerty123, database: test, }, }, # 也可以直接用 DB_URL 字符串作为连接 default: postgres://postgres:qwerty123localhost:5432/events, }, apps: { models: { models: [__main__], # 若不指定 default_connection默认使用名为 default 的连接 default_connection: default, } }, }, )注意connections字典中default键被赋值两次实际以最后一次为准此处意在演示同一种连接可用 dict 或 DB_URL 两种写法。底层 Tortoise.init 的 docstring 还补充了可选顶层键routers数据库路由、use_tzdatetime 是否时区感知与timezone。方式二config_file配置文件传入.json或.yml需已安装 PyYAML文件路径文件内容格式与config字典完全一致。方式三db_url modules最简写法本示例采用的形式适合单连接、单应用的快速起步。modules是{应用名: [模型模块列表]}的映射模型模块可以是模块名字符串也可以是ModuleType对象。generate_schemas仅限开发环境generate_schemasTrue会在启动时调用Tortoise.generate_schemas()自动建表。官方在 tortoise/init.py#L497-L510 中给出了明确警告建表在表已存在时会失败因此不建议在生产工作流中使用。它主要适用于开发环境或 SQLite:memory:内存数据库场景生产环境应改用 aerich 迁移工具 管理表结构。_enable_global_fallback内部开关以下划线开头属于内部参数默认True。它控制是否将当前 Tortoise 上下文设置为全局回退上下文global fallback相关机制定义在 tortoise/context.py用于在显式上下文之外也能访问到连接。普通开发者保持默认即可。底层原理Sanic 生命周期钩子如何驱动 ORMregister_tortoise的价值在于它把 Tortoise-ORM 的初始化/关闭与 Sanic 的服务器生命周期精确对齐。从 tortoise/contrib/sanic/init.py#L84-L111 可以看到完整实现async def tortoise_init() - None: await Tortoise.init( configconfig, config_fileconfig_file, db_urldb_url, modulesmodules, _enable_global_fallback_enable_global_fallback, ) logger.info(Tortoise-ORM started, %s, %s, get_connections()._get_storage(), Tortoise.apps) if generate_schemas: app.main_process_start async def init_orm_main(app): await tortoise_init() logger.info(Tortoise-ORM generating schema) await Tortoise.generate_schemas() app.before_server_start async def init_orm(app): await tortoise_init() if generate_schemas and getattr(app, _test_manager, None): # Running by sanic-testing await Tortoise.generate_schemas() app.after_server_stop async def close_orm(app): await Tortoise.close_connections() logger.info(Tortoise-ORM shutdown)整个生命周期分三个阶段1. 主进程启动main_process_start仅当generate_schemasTrue时注册。Sanic 采用多进程模型main_process_start在主进程master中只执行一次这里完成 Tortoise 初始化并建表避免多个 worker 并发建表引发冲突。2. 每个 worker 启动前before_server_start无论是否建表都会注册。由于每个 Sanic worker 拥有独立的事件循环与连接池必须在每个 worker 内各自调用一次tortoise_init()这正是 Tortoise.init 所述的“加载应用与模型、配置连接但不立即连接首次查询时才惰性建立连接/连接池”。这里还包含一个针对 sanic-testing 的兼容分支当app._test_manager为真ReusableClient 不会触发真正的main_process_start时在before_server_start中补一次建表。3. 服务停止后after_server_stop调用Tortoise.close_connections()干净地关闭所有连接。tortoise/init.py#L470-L481 的 docstring 强调进程退出前必须关闭连接否则事件循环可能因等待连接关闭而永远无法结束——这正是“teardown 清理”环节存在的意义。DB_URL 格式速查示例使用的sqlite://db.sqlite3只是 DB_URL 的一种。Tortoise-ORM 支持更通用的形式详见 docs/databases.rst{DB_TYPE}://{USERNAME}:{PASSWORD}{HOST}:{PORT}/{DB_NAME}?{PARAM1}value{PARAM2}value常见类型sqlite://{DB_FILE}注意当 DB_FILE 是绝对路径/data/db.sqlite3时需写三个斜杠sqlite:///data/db.sqlitepostgres://postgres:passdb.host:5432/somedbasyncpg亦可显式写作asyncpg://或psycopg://mysql://myuser:mypassdb.host:3306/somedbmssql://myuser:mypassdb.host:1433/somedb可携带 ODBC driver 参数。另外 docs/databases.rst#L33-L62 特别提醒密码含%后跟合法十六进制字符时可能被 URL 解析器误判为百分号编码此时应改用 dict 格式配置以绕开 URL 解析。用 sanic-testing 验证集成examples/sanic/_tests.py 展示了如何对 Sanic Tortoise 应用做端到端测试import re from pathlib import Path import pytest from sanic_testing.reusable import ReusableClient try: import main except ImportError: if (cwd : Path.cwd()) (parent : Path(__file__).parent): dirpath . else: dirpath str(parent.relative_to(cwd)) print(fYou may need to explicitly declare python path:\n\nexport PYTHONPATH{dirpath}\n) raise pytest.fixture(scopemodule) def anyio_backend() - str: return asyncio pytest.fixture def client(): sanic_app main.app # make register_tortoise treat this as sanic-testing (ReusableClient doesnt set this flag) sanic_app._test_manager True client ReusableClient(sanic_app) with client: yield client def test_basic_test_client(client): request, response client.get(/) assert response.status 200 assert b{users:[ in response.body request, response client.post(/user) assert response.status 200 assert re.match(rb{user:User \d: New User}$, response.body)两个值得注意的实践细节app._test_manager True注释说明了关键点——ReusableClient不会设置该标志手动置为True后register_tortoise内部的before_server_start分支才会在测试环境中补建表对应源码 tortoise/contrib/sanic/init.py#L105-L107anyio_backend返回asyncio测试运行在 asyncio 事件循环上与 Tortoise-ORM 的异步驱动一致。测试断言验证了端到端链路GET /返回空用户列表 JSONPOST /user创建用户并返回User N: New User格式的 JSON说明初始化、建表、查询、写入、关闭整条生命周期都工作正常。生产环境落地建议综合官方文档与源码可以总结出以下实践要点关闭自动建表generate_schemas仅适合开发/内存库生产请使用 aerich 迁移 管理 schema连接清理交给钩子不要手动调用Tortoise.close_connections()after_server_stop已保证退出时干净关闭避免事件循环悬挂多 worker 天然安全before_server_start在每个 worker 内各自初始化连接池多进程部署无需额外加锁处理连接初始化复杂配置选 dict/文件多数据库、连接路由routers、时区设置use_tz/timezone等场景请使用config或config_file方式完整能力参见 Tortoise.init 文档。相关文档延伸阅读Sanic 集成官方说明docs/contrib/sanic.rst示例文档docs/examples/sanic.rst数据库支持与 DB_URL 详解docs/databases.rst连接管理文档docs/connections.rst迁移工具生产建表推荐docs/migration.rst赞分享数据库后端【免费下载链接】tortoise-ormFamiliar asyncio ORM for python, built with relations in mind项目地址https://gitcode.com/gh_mirrors/to/tortoise-orm点击查看免费下载相关推荐Tortoise-ORM 与 Sanic 集成实战register_tortoise 生命周期接入与配置详解Tortoise ORM 与 Sanic 集成实战register_tortoise 生命周期接入与配置详解 本指南基于 Tortoise ORM 官方文档中数据库后端Tortoise-ORM 与 Quart 集成实战register_tortoise 生命周期管理与 CLI 全解析Tortoise ORM 与 Quart 集成实战register_tortoise 生命周期管理与 CLI 全解析 本指南围绕 Tortoise ORM 官数据库后端Tortoise-ORM 与 BlackSheep 集成指南register_tortoise 生命周期管理详解Tortoise ORM 与 BlackSheep 集成指南register_tortoise 生命周期管理详解 Tortoise ORM 为 BlackSh数据库后端上一篇Carbon-3B部署指南如何在本地环境快速运行这个基因组基础模型的完整教程下一篇Video2X终极指南专业视频超分辨率与帧插值解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考