升级至psycopg 3.x为何导致数据库连接超时？

问题场景 #

我有一个Django 5.x应用，原本使用psycopg2，升级到psycopg 3（卸载所有psycopg2相关组件，安装psycopg[binary]）后，并行运行测试套件时突然出现此前从未遇到的connection timeout expired错误。数据库配置中OPTIONS里的connect_timeout设为3，移除该配置后一切恢复正常。

核心原因：psycopg 3与psycopg2的连接机制差异 #

psycopg 3在连接超时的处理逻辑上和psycopg2存在明显不同，这是触发问题的关键：

• connect_timeout参数作用范围更严格：psycopg2依赖的旧版libpq中，connect_timeout是整个连接流程（TCP握手、认证、数据库选择）的总超时；而psycopg 3使用的新版libpq中，该参数仅控制TCP连接阶段的超时，后续的认证、数据库协商等步骤不计入这个超时时间。并行测试时数据库连接请求激增，TCP握手或后续环节稍有延迟就会触发超时。
• 并发连接处理逻辑差异：psycopg3的连接建立流程与Django数据库连接池的交互方式和psycopg2不同。并行测试时，多线程/进程同时请求数据库连接，psycopg3在connect_timeout限制下，更容易因为数据库端的连接队列等待而触发超时；而psycopg2会在这类场景下自动做兼容处理，比如隐性延长等待时间。
• 参数传递精度提升：psycopg3会将OPTIONS中的参数直接、精确地传递给libpq，没有额外的兼容包装；而psycopg2可能对connect_timeout做了适配，比如忽略某些低延迟场景下的超时触发。

解决办法 #

• 直接移除connect_timeout参数：这是最直接的解决方案，libpq会使用默认的超时设置（通常足够应对并行测试的连接压力）。
• 调大超时时间：如果必须保留超时控制，可以尝试将connect_timeout的值调高（比如设为10），给TCP连接和后续流程留出足够缓冲时间。
• 优化数据库连接池配置：通过Django的数据库参数控制并行连接数量，避免数据库端因连接过载而排队：

DATABASES = {
    "default": {
        # 原有配置...
        "CONN_MAX_AGE": 60,  # 保持连接的最长时间
        "MAX_CONNS": 20,     # 最大并发连接数，根据测试并行度调整
    }
}

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