FastAPI+SQLModel连接PostgreSQL报错：无效连接选项'plant'

问题根源 #

这个错误是因为psycopg收到了不支持的连接参数plant，结合你提到的_psycopg_common.py里的异常配置，大概率是本地环境存在自定义修改、连接URL错误或环境污染导致的，官方SQLAlchemy包不会硬编码这类配置。

排查与解决步骤 #

1. 检查数据库连接URL格式
   确保你的PostgreSQL连接URL符合标准格式，没有多余的plant参数：

   # 正确格式
   postgresql://your_username:your_password@host:port/your_dbname
   # 错误示例（会触发问题）
   postgresql://user:pass@host:port/db?plant=xxx
   

   检查项目中配置的DATABASE_URL环境变量或硬编码值，删除任何包含plant=的片段。

2. 检查引擎创建代码的连接参数
   查看创建SQLModel引擎的代码，确认没有传递多余的plant参数：

   # 错误示例（需删除connect_args中的plant）
   engine = create_engine(
       DATABASE_URL,
       connect_args={"plant": "some_value"}
   )
   

   确保connect_args只包含psycopg支持的参数，比如sslmode等。

3. 排查本地是否存在覆盖官方包的文件
   项目根目录下如果存在sqlalchemy文件夹或同名.py文件，会优先加载本地文件覆盖虚拟环境的官方包。执行以下命令检查：

   ls -la | grep sqlalchemy
   

   如果发现相关文件/文件夹，直接删除。

4. 验证虚拟环境隔离性
   确认你正在使用的是项目的虚拟环境：

   # 检查当前Python路径
   which python
   # 查看SQLAlchemy安装路径
   pip show sqlalchemy
   

   确保输出的路径指向你的.venv目录。如果全局Python环境存在SQLAlchemy，建议卸载全局版本，避免环境污染。

5. 彻底清理并重建虚拟环境
   uv缓存可能保留了修改过的包，执行以下步骤完全重建环境：

   # 删除虚拟环境
   rm -rf .venv
   # 清理uv缓存
   uv cache clean
   # 重新创建环境并安装依赖
   uv venv && uv sync
   

6. 用psql测试数据库连接
   排除数据库本身的问题，直接用psql连接测试：

   psql -h localhost -p 5432 -U your_db_user -d your_db_name
   

   如果psql能正常连接，说明数据库配置无问题，问题仍出在Python代码或依赖环境。

内容的提问来源于stack exchange，提问作者Raoul Luqué