Tortoise-ORM 在 FastAPI 中打印 SQL 日志的方法

在使用 FastAPI 框架结合 Tortoise-ORM 进行开发时，开发者经常需要查看 ORM 生成的 SQL 语句，这对于调试和性能优化非常重要。本文将详细介绍如何在 FastAPI 应用中配置 Tortoise-ORM 以输出 SQL 日志。

日志级别配置

Tortoise-ORM 使用 Python 标准库的 logging 模块来记录日志。要查看生成的 SQL 语句，最简单的方法是将日志级别设置为 DEBUG。这可以通过以下方式实现：

import logging

# 设置 Tortoise ORM 的日志级别为 DEBUG
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("tortoise")
logger.setLevel(logging.DEBUG)

在 FastAPI 中集成

当使用 FastAPI 的 register_tortoise 方法注册 Tortoise-ORM 时，可以在应用启动前配置日志级别：

from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise

app = FastAPI()

# 先配置日志
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("tortoise")
logger.setLevel(logging.DEBUG)

# 然后注册 Tortoise ORM
register_tortoise(
    app,
    db_url="sqlite://db.sqlite3",
    modules={"models": ["app.models"]},
    generate_schemas=True,
)

日志输出内容

配置完成后，应用运行时会在控制台输出类似以下的 SQL 日志：

DEBUG:tortoise.db_client:INSERT INTO "admin" ("name") VALUES ('test')
DEBUG:tortoise.db_client:SELECT "id","name" FROM "admin" WHERE "id"=1

高级日志配置

如果需要更精细地控制日志输出，可以单独配置 Tortoise 的不同组件：

# 配置连接池日志
logging.getLogger("tortoise.connection").setLevel(logging.DEBUG)
# 配置查询日志
logging.getLogger("tortoise.query").setLevel(logging.DEBUG)
# 配置模型日志
logging.getLogger("tortoise.models").setLevel(logging.DEBUG)

生产环境注意事项

在生产环境中，不建议一直保持 DEBUG 日志级别，因为这会影响性能并可能暴露敏感信息。可以考虑以下策略：

1. 只在开发环境启用 SQL 日志
2. 使用环境变量控制日志级别
3. 将 SQL 日志输出到单独的文件而非控制台

替代方案

除了日志配置外，Tortoise-ORM 还提供了 explain() 方法，可以获取查询的执行计划：

query = await Admin.all().explain()
print(query)

这种方法不会记录所有 SQL，但可以在需要时分析特定查询的性能特征。

通过合理配置日志系统，开发者可以更好地理解和优化 Tortoise-ORM 在 FastAPI 应用中的数据库操作行为。