FastAPI与peewee应用出现‘数据库连接未打开’错误的原因

核心问题原因 #

你遇到的问题本质是Peewee连接的线程本地特性和FastAPI的并发模型不匹配：

1. Peewee的PooledDatabase使用线程本地存储管理连接，每个线程只能看到自己打开的连接。你在startup事件中打开的连接属于主线程，而FastAPI处理请求时会用独立的工作线程/异步任务，这些线程无法共享主线程的连接，自然报“连接未打开”错误。
2. 加async修饰符后能运行，是因为异步路由在事件循环线程执行，刚好和中间件的with database上下文处于同一个线程，能共享连接；但同步路由会被FastAPI放到单独的线程池执行，和中间线程上下文隔离，所以还是报错。

另外，用startup/shutdown全局管理连接本身就是错误的——Peewee连接池的设计是为每个请求分配/释放连接，而非全局保持一个连接。

正确解决方案 #

1. 同步路由：用依赖项管理连接上下文 #

依赖项会在每个请求的处理线程中执行，确保连接上下文和请求线程绑定：

from fastapi import Depends, FastAPI
import models

# 数据库初始化保持不变
database = PooledSqliteDatabase('foobar.db', autoconnect=False, stale_timeout=60)
with database:
    database.create_tables([models.Foobar])

app = FastAPI()
app.include_router(foobar_router)

# 定义数据库依赖，每个请求自动获取/释放连接
def get_db():
    with database:
        yield database

# 同步路由示例
@app.get("/foobars")
def list_foobars(db=Depends(get_db)):
    return list(models.Foobar.select())

2. 异步路由：包装同步操作到线程池 #

Peewee是同步库，异步路由中必须把数据库操作放到线程池执行，避免阻塞事件循环，同时仍用依赖项管理连接：

import asyncio
from fastapi import Depends, FastAPI
import models

# 数据库初始化同上
database = PooledSqliteDatabase('foobar.db', autoconnect=False, stale_timeout=60)
with database:
    database.create_tables([models.Foobar])

app = FastAPI()
app.include_router(foobar_router)

def get_db():
    with database:
        yield database

# 异步路由示例
@app.get("/foobars")
async def list_foobars(db=Depends(get_db)):
    # 把同步数据库操作放到线程池执行
    foobars = await asyncio.to_thread(lambda: list(models.Foobar.select()))
    return foobars

关键实践总结 #

• 保持autoconnect=False，避免Peewee自动创建未管理的连接。
• 放弃全局startup/shutdown连接方式，改用请求级依赖项管理连接上下文，这是最贴合Peewee连接池设计的方案。
• 异步路由必须用asyncio.to_thread包装同步数据库操作，防止阻塞FastAPI的事件循环。

内容的提问来源于stack exchange，提问作者Steffen