Psycopg3与PgBouncer集成时的预处理语句配置指南

在使用Psycopg3连接PostgreSQL数据库时，预处理语句(Prepared Statements)是一个重要的性能优化特性。然而当与PgBouncer这样的连接池工具结合使用时，预处理语句的配置需要特别注意，否则可能会遇到"prepared statement does not exist"等错误。

预处理语句的基本原理

Psycopg3中的预处理语句机制允许将SQL查询预先编译并存储在数据库服务器端，后续执行时只需传递参数即可。这可以显著提高重复执行相同查询模式的性能。Psycopg3通过两个关键参数控制预处理行为：

1. prepare_threshold：决定一个查询被执行多少次后才转换为预处理语句，默认值为5
2. prepared_max：限制单个连接上最多可缓存的预处理语句数量，默认值为100

与PgBouncer的兼容性问题

当使用PgBouncer时，特别是在事务池模式下，预处理语句可能会遇到问题。这是因为PgBouncer可能会将客户端连接重新分配给不同的后端PostgreSQL连接，而预处理语句是绑定到特定后端连接的。

在PgBouncer 1.22及以上版本中，如果客户端使用libpq 17或更高版本，可以通过新的DEALLOCATE ALL协议解决这个问题。但对于使用旧版libpq的客户端，需要采用替代方案。

解决方案

方案一：完全禁用预处理语句

将prepare_threshold设置为None可以完全禁用预处理语句功能：

# 创建连接时设置
conn = psycopg.connect(dsn, prepare_threshold=None)

# 或者在已有连接上设置
conn.prepare_threshold = None

这种方法简单可靠，但会失去预处理语句带来的性能优势。

方案二：禁用预处理语句的自动释放

对于PgBouncer 1.22+但无法使用libpq 17的环境，可以将prepared_max设置为None来禁止Psycopg自动释放预处理语句：

# 创建连接后设置
conn.prepared_max = None

这种方法允许继续使用预处理语句，但需要注意：

1. 预处理语句会持续累积，可能占用较多服务器内存
2. 需要确保应用程序不会无限制地创建新的预处理语句

在SQLAlchemy中的配置

如果通过SQLAlchemy使用Psycopg3，可以通过事件监听器设置这些参数：

from sqlalchemy import event
from sqlalchemy import create_engine

engine = create_engine("postgresql+psycopg://user:pass@host/db")

@event.listens_for(engine, "connect")
def set_prepare_threshold(dbapi_conn, connection_record):
    dbapi_conn.prepare_threshold = None
    # 或者
    # dbapi_conn.prepared_max = None

最佳实践建议

1. 优先考虑升级到支持DEALLOCATE ALL的libpq 17+和PgBouncer 1.22+
2. 如果无法升级，根据应用特点选择：
   • 对于短查询居多的应用，禁用预处理语句(方案一)
   • 对于复杂查询居多的应用，禁用自动释放(方案二)但需监控内存使用
3. 在生产环境部署前，务必进行充分的性能测试

通过合理配置这些参数，可以在保证稳定性的同时，尽可能发挥Psycopg3的性能优势。