排查Django环境中PostgreSQL 10.13版本来源问题

我正在重启一个两年未本地运行的Django项目，处理各类过期环境问题时遇到特殊情况：运行python mysite/manage.py runserver时，Django提示django.db.utils.NotSupportedError: PostgreSQL 13 or later is required (found 10.13)，但当前使用的venv中，pip list显示PostgreSQL相关包版本并非10.13，psql -V显示版本为12.3，尝试卸载10.13版本失败。该错误在数据库连接时触发，需要了解如何追踪这个10.13版本的来源？

环境信息：

• pip list：Django 5.1、psycopg2 2.9.9、psycopg2-binary 2.9.9、psycopg2-pool 1.2
• Python版本：3.12.5
• PATH变量内容：/Users/dkaplan/.vscode/extensions/ms-python.python-2024.12.3-darwin-x64/python_files/deactivate/bash:/Users/dkaplan/family-django/.venv/bin:/Library/Frameworks/Python.framework/Versions/3.12/bin:/Library/Frameworks/Python.framework/Versions/3.12/bin:/Library/Frameworks/Python.framework/Versions/3.10/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/dkaplan/.m2:/Applications/Postgres.app/Contents/Versions/latest/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/Users/dkaplan/.vscode/extensions/ms-python.python-2024.12.3-darwin-x64/python_files/deactivate/bash:/Users/dkaplan/family-django/.venv/bin:/Library/Frameworks/Python.framework/Versions/3.12/bin:/Library/Frameworks/Python.framework/Versions/3.10/bin
• 数据库配置：

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql_psycopg2",
        "NAME": DB_DATABASE,
        "USER": DB_USER,
        "PASSWORD": DB_PASSWORD,
        "HOST": DB_HOST,
        "PORT": "5432",
        "OPTIONS": DB_OPTIONS,
    }
}

1. 确认实际连接的数据库服务端版本 #

Django报错中的版本是你正在连接的数据库服务端版本，和本地客户端（psql）、Python包版本无关。直接连接数据库验证：

• 执行命令连接指定数据库：psql -h ${DB_HOST} -p 5432 -U ${DB_USER} -d ${DB_DATABASE}
• 连接成功后执行：SELECT version();
  输出结果即为Django检测到的版本，大概率你的数据库服务端确实是10.13。

2. 排查本地多PostgreSQL实例 #

如果DB_HOST是localhost或127.0.0.1，检查本地是否运行了多个版本的PostgreSQL：

• 查看PostgreSQL进程：ps aux | grep postgres，确认是否有10.13版本的进程在运行
• 检查端口占用：lsof -i :5432，确认哪个进程占用5432端口，对应路径是否为旧版本PostgreSQL

3. 验证psycopg2链接的libpq库版本 #

psycopg2可能编译时链接了系统中旧版本的libpq库：

• 进入Python交互环境执行：

import psycopg2
print(psycopg2.__libpq_version__)
# 转换为可读版本号：
print(f"Libpq version: {psycopg2.__libpq_version__ // 10000}.{psycopg2.__libpq_version__ % 10000 // 100}.{psycopg2.__libpq_version__ % 100}")

如果输出为10.13，说明psycopg2依赖了旧的libpq库。

4. 检查环境变量与路径 #

• 确认当前psql路径：which psql，看是否指向预期的12.3版本路径
• 检查PostgreSQL相关环境变量：echo $PGHOME、echo $PGDATA，确认是否指向旧版本目录

5. 重新编译psycopg2链接最新库 #

如果是psycopg2依赖旧libpq，重新安装并指定链接最新库（以Postgres.app为例）：

pip uninstall -y psycopg2 psycopg2-binary
export LDFLAGS="-L/Applications/Postgres.app/Contents/Versions/latest/lib"
export CPPFLAGS="-I/Applications/Postgres.app/Contents/Versions/latest/include"
pip install psycopg2-binary

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