Psycopg 3&SQLAlchemy 2：常规操作中DuplicatePreparedStatement异常的诱因与处理

应用采用SQLAlchemy搭配Psycopg驱动与TimescaleDB交互，近期执行查询时频繁触发以下错误：

psycopg.errors.DuplicatePreparedStatement: prepared statement "_pg3_3" already exists

当前无应用更新，数据库负载极低，无法定位触发异常的行为变动，需解决以下问题：

1. 常规低负载场景下该异常的成因是什么？是否为底层库的Bug？
2. 如何在无显著停机的情况下修复该问题？是否需手动执行DEALLOCATE或重启应用Worker？
3. 如何避免该问题再次发生？

相关代码示例 #

from datetime import datetime as Datetime
from typing import Any

from sqlalchemy import TIMESTAMP, select
from sqlalchemy.ext.asyncio import AsyncSession as BaseAsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase

from ..config import settings


class Base(DeclarativeBase):
    type_annotation_map = {
        Datetime: TIMESTAMP(timezone=True),
    }


async_engine = create_async_engine(
    settings.SQLALCHEMY_DATABASE_URI,
    isolation_level="READ COMMITTED",
    pool_pre_ping=True,
    pool_size=20,
    pool_recycle=3600,
    max_overflow=5,
)


AsyncSession = async_sessionmaker(async_engine, autobegin=False)


class SensorRecord(Base):
    __tablename__ = "sensor_records"

    ...  # attributes here


async def fetch_prev_record(session: BaseAsyncSession, ...):
    query = select(SensorRecord)
    return ...  # more SQL and logic here

补充说明：已通过蓝绿部署重启应用解决问题，但需明确根因以防范复发。

1. 低负载场景下的异常成因 #

该错误本质是Psycopg（尤其是Psycopg3）的预准备语句命名冲突，低负载场景下的核心成因包括：

• 连接池状态异常：尽管配置了pool_recycle=3600，但如果TimescaleDB端的连接超时设置短于应用的pool_recycle值，数据库会主动断开闲置连接，而应用连接池仍会复用这些"半失效"连接。当复用这类连接时，Psycopg尝试重新注册预准备语句，但之前的语句在数据库端未被正确释放，导致命名冲突。
• 异步连接生命周期管理疏漏：异步场景下，若会话未通过正确的上下文管理器关闭、连接未归还池时被重复调用，会导致预准备语句的状态在连接上残留，再次使用时触发冲突。
• 底层库已知Bug：部分旧版本的Psycopg3（如低于3.1.10的版本）存在预准备语句管理的Bug，在连接复用或事务异常回滚后，未正确清理已注册的语句标识，导致再次使用时触发重复定义错误。

2. 无停机修复方案 #

可按以下优先级操作，避免服务中断：

• 手动释放冲突语句：直接在数据库端执行DEALLOCATE "_pg3_3";（注意保留引号，因为语句名包含特殊字符），若存在多个类似冲突语句，可执行DEALLOCATE ALL;一次性释放所有预准备语句。此方式无需重启应用，适合快速临时修复。
• 滚动重启应用Worker：如果手动释放后问题复现，或无法定位所有冲突语句，可采用分批重启Worker的方式（如你已使用的蓝绿部署），逐批替换旧Worker，不会导致整体服务停机。重启后应用会建立新连接，预准备语句将重新初始化，避免冲突。
• 无需重启数据库：数据库本身无问题，重启数据库会导致所有连接断开，影响范围更大，不建议操作。

3. 长期防范措施 #

• 升级Psycopg版本：切换到最新稳定版的Psycopg3（至少3.1.10以上），官方已修复多个预准备语句管理的Bug。
• 调整连接池参数：
  • 检查TimescaleDB的idle_in_transaction_session_timeout设置，确保应用的pool_recycle值小于该超时时间，避免数据库主动断开连接后应用复用无效连接。
  • 开启pool_reset_on_return=True（SQLAlchemy 1.4+支持），确保连接归还池时重置所有状态，包括清理预准备语句。
• 规范异步会话管理：所有异步会话必须通过async with上下文管理器使用，保证会话关闭时正确释放连接并清理状态：

  async def fetch_data(...):
      async with AsyncSession() as session:
          async with session.begin():
              query = select(SensorRecord)
              result = await session.execute(query)
              return result.scalars().first()
  

• 临时应急方案（禁用预准备语句）：若上述方案均无效，可在创建引擎时添加参数prepared_statement_cache_size=0，强制禁用预准备语句缓存，但会牺牲部分查询性能，仅作为临时过渡方案。

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