连接PostgreSQL 16时Django误报版本不兼容（实际版本匹配）

问题概述 #

Django 4.2应用连接远程PostgreSQL 16.4数据库时触发NotSupportedError，错误提示要求PostgreSQL 12或更高版本，但检测到版本为10.23。实际数据库版本确认为16.4，且应用曾成功执行migrate、createsuperuser等操作，后续才出现该问题：

• Docker环境使用psycopg2-binary时触发问题
• 部署到Heroku改用psycopg3则无异常

相关配置与依赖 #

数据库配置（settings.py） #

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

依赖清单 #

Docker环境（触发问题）

django==4.2.13
psycopg2-binary==2.9.9
# 其他项目依赖...

Heroku环境（正常工作）

django==4.2.13
psycopg3==3.1.20
# 其他项目依赖...

错误堆栈信息 #

django.db.utils.NotSupportedError: PostgreSQL 12 or later is required (got 10.23).
  File "/usr/local/lib/python3.11/site-packages/django/db/backends/postgresql/base.py", line 277, in get_new_connection
    connection = Database.connect(**conn_params)
  File "/usr/local/lib/python3.11/site-packages/psycopg2/__init__.py", line 122, in connect
    conn = _connect(dsn, connection_factory=connection_factory, **kwasync)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/app/manage.py", line 22, in <module>
    main()
  File "/app/manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  File "/usr/local/lib/python3.11/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
    utility.execute()
  File "/usr/local/lib/python3.11/site-packages/django/core/management/__init__.py", line 436, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/usr/local/lib/python3.11/site-packages/django/core/management/base.py", line 412, in run_from_argv
    self.execute(*args, **cmd_options)
  File "/usr/local/lib/python3.11/site-packages/django/core/management/base.py", line 458, in execute
    output = self.handle(*args, **options)
  File "/usr/local/lib/python3.11/site-packages/django/core/management/base.py", line 106, in wrapper
    res = handle_func(*args, **options)
  File "/usr/local/lib/python3.11/site-packages/django/core/management/commands/migrate.py", line 156, in handle
    self.check(databases=[database])
  File "/usr/local/lib/python3.11/site-packages/django/core/management/base.py", line 485, in check
    all_issues = checks.run_checks(
  File "/usr/local/lib/python3.11/site-packages/django/core/checks/registry.py", line 88, in run_checks
    new_errors = check(app_configs=app_configs, databases=databases)
  File "/usr/local/lib/python3.11/site-packages/django/core/checks/database.py", line 132, in check_database_backends
    issues.extend(check_backend(database))
  File "/usr/local/lib/python3.11/site-packages/django/core/checks/database.py", line 115, in check_backend
    issues.extend(conn.validation.check(**kwargs))
  File "/usr/local/lib/python3.11/site-packages/django/db/backends/postgresql/validation.py", line 9, in check
    connection = self.connection.get_new_connection(conn_params)
  File "/usr/local/lib/python3.11/site-packages/django/db/backends/postgresql/base.py", line 290, in get_new_connection
    raise ImproperlyConfigured(str(e)) from e
django.core.exceptions.ImproperlyConfigured: PostgreSQL 12 or later is required (got 10.23).

解决方案 #

1. 修复psycopg2-binary与libpq版本不匹配问题 #

psycopg2-binary自带编译好的libpq库，若该库版本较旧（对应PostgreSQL 10.x），会导致读取到错误的数据库版本：

• 升级psycopg2-binary到最新兼容版本：

  pip install --upgrade psycopg2-binary
  

• 改用编译版psycopg2（需系统安装依赖），使用系统中较新的libpq库：

  pip uninstall psycopg2-binary
  pip install psycopg2
  

  Dockerfile中添加依赖安装步骤（Debian/Ubuntu为例）：

  RUN apt-get update && apt-get install -y libpq-dev gcc
  

2. 验证Docker容器的数据库连接目标 #

确认容器是否连接到正确的PostgreSQL 16.4实例，而非旧版本实例：
在容器内执行命令验证版本：

psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT version();"

若返回10.23，需检查DB_HOST、DB_PORT环境变量是否指向正确的远程地址。

3. 清除Django缓存并重启容器 #

Django可能缓存了旧的数据库版本信息：

python manage.py clearcache

重启Docker容器，确保进程重新建立连接并读取最新配置。

4. 切换到psycopg3 #

若上述方法无效，可直接改用psycopg3，其版本检测逻辑更准确，对新PostgreSQL版本支持更完善：
将requirements.txt中的psycopg2-binary替换为：

psycopg3==3.1.20

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